Naming exception (documented): skillforge's checklist forbids

claude

or

anthropic

in a skill name. This skill is a deliberate exception: it operates on the literal

CLAUDE.md

artifact, so the precision of the name is the value. Treat this as the only such exception in the library.

The removability test: "For every line in CLAUDE.md, ask — if I removed this, would Claude make a mistake? If not, remove it." — Anthropic, Claude Code Best Practices

1. Resolve the target file. If multiple candidates exist, list them and ask.
2. Read the file in full. Note size (lines, characters).
3. Read sibling files for cross-tier duplication detection:

   • ~/.claude/CLAUDE.md

     (if improving a project file)

   • ./CLAUDE.local.md

     (if present)

   • ./.claude/rules/*.md

     (path-scoping in use?)

• DELETE: K lines
• ADD: L sections
• REWRITE: J lines
• Net change: ±N lines (final: M lines)

Edit

Write

1. Re-measure: print new size, new rubric pass rate.
2. Suggest: "Run

   /claude-md audit

   afterward to verify no drift introduced."
3. If the file now has obvious path-scoped subsections, suggest splitting them into

   .claude/rules/<topic>.md

   (R9).

1. ## Project

   (1–2 lines: what this is, who uses it)

2. ## Stack

   (1–3 lines: framework, language, deployment target)

3. ## Commands

   (Build / Dev / Test single / Test all / Lint / Type check — short, exact)

4. ## Architecture

   (folder → purpose mapping; not full directory listing)

5. ## Rules

   (under 15 items; negative rules count; emphasis on the load-bearing one)

6. ## Workflow

   (how the user wants Claude to approach tasks: minimal changes, ask vs act, commit conventions)

7. ## Out of scope

   (files/integrations Claude should not touch)

• Only modify files, functions, and lines directly related to the current task. Do not refactor, rename, or reformat anything I did not ask you to change. Note other issues at the end; don't touch them.

• Before any change that significantly alters existing content (rewriting sections, restructuring, changing tone): stop, describe what you're about to change and why, wait for confirmation.

• Before deleting a file, overwriting code, dropping records, or removing dependencies: stop, list what will be affected, ask for explicit confirmation in the current message. "You mentioned this earlier" is not confirmation.

• Production hard-stops requiring in-session confirmation: deploys/pushes, migrations or schema changes, outbound API calls, any command with irreversible side effects.

  (If a stop must hold 100% of the time, a PreToolUse hook is the real enforcement — CLAUDE.md compliance ceilings around 80%.)

• After any coding task, end with: files changed, one-line summary per file, files intentionally not touched, follow-up needed.

• NEVER commit .env files or secrets

• NEVER run git push --force without explicit confirmation

• IMPORTANT: run type check after every code change

• Make minimal changes, don't refactor unrelated code

• Create separate commits per logical change, not one giant commit

• When unsure between two approaches, explain both and let me choose

• For architecture decisions or non-trivial features: work through the problem step by step before writing code. Show reasoning and where you're uncertain, then implement.

• Match response length to task complexity. Don't pad with restatements of the question or closing summaries.

• If uncertain about a fact, statistic, date, or technical detail, say so explicitly rather than filling the gap with plausible-sounding content.

• Personality instructions ("be a senior engineer")
• Code-formatter rules the linter already handles
• Duplicate rules across tiers

• @-imports

  of full README / huge docs (they enter the context window at launch)
• Anything Claude learns on its own via auto memory
• (V2) Auto-generated bulk. Never

  /init

  -and-forget or paste an LLM-generated context file. Controlled study: a curated context file gives ~+4pp task quality at ~20% token overhead, but an auto-generated one reduces task success ~0.5–2% while raising cost 20–23%. Curate ruthlessly; more context is not better. (arXiv 2026, AGENTS.md efficiency study.)

1. Find every

   CLAUDE.md

   under your projects roots (adjust to where you keep code, e.g.

   ~/Projects

   ,

   ~/work

   ):
   bash

   find ~/Projects ~/work -name 'CLAUDE.md' \
     -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/vendor/*' 2>/dev/null

2. For each file, note the owning project and size (line count).

• (?i)(secret|token|api[_-]?key|password)\s*[:=]\s*['"]\S{8,}['"]

• (?i)auth[_-]?secret\s*[:=]\s*\S{8,}

• Base64-ish JWT prefixes:

  eyJ[A-Za-z0-9_-]{10,}

• URLs with embedded credentials:

  https?://[^:/\s]+:[^@\s]+@

• Stripe/OpenAI/Anthropic key prefixes:

  sk_live_

  ,

  sk_test_

  ,

  pk_live_

  ,

  sk-ant-

  ,

  sk-proj-

• Supabase/Neon connection strings:

  postgres(ql)?://[^:]+:[^@]+@

git filter-repo --path CLAUDE.md --invert-paths

1. MCP servers — diff against

   settings.json

   /

   .mcp.json

   /

   mcp.json

2. API routes — grep for routes named in CLAUDE.md; verify each exists in

   src/app/api/

   or routes file
3. Cron jobs — count asserted vs actual

   */cron*

   files /

   vercel.json

   crons /

   wrangler.toml

   triggers
4. Env vars — every env var named should appear in

   .env.example

   or be read by code (

   process.env.<NAME>

   /

   os.environ["<NAME>"]

   )
5. External services — flag contradictions ("uses Brevo SMTP" but code imports

   @getbrevo/brevo

   REST client)
6. Directory structure — diff enumerated dirs against

   ls

   output

1. Detect duplicate section headings (

   ^## 

   ,

   ^### 

   appearing ≥2 times)
2. Detect near-duplicate paragraphs (same first 60 characters on two different lines)
3. Report any line contradicting another line in the same file

1. Count instructions — any line starting with imperative verb (Always, Never, Use, Don't, Prefer, Avoid, Run, Check, Write, Edit, Follow) OR inside a bullet list under "Rules/Conventions/Do/Don't" heading
2. Budget thresholds:
   • ≤ 100 instructions: 🟢 healthy
   • 100–200: 🟡 monitor

   • 200: 🟠 over budget — suggest splits or cuts

3. Descriptive vs prescriptive classifier:
   • Descriptive = describes what code already shows ("this is a Next.js app with Postgres")
   • Prescriptive = tells Claude what to do ("when editing migrations, add both up and down") Report ratio. Descriptive lines are budget waste.

• Lines starting with

  NEVER

  ,

  Never

  ,

  Always

  ,

  MUST

  ,

  Do not

  followed by a verb
• Rules naming destructive commands:

  rm -rf

  ,

  git push --force

  ,

  git reset --hard

  ,

  DROP TABLE

  ,

  truncate

  ,

  vercel --prod

  ,

  gcloud ... delete

• Rules requiring 100% pre-commit gates: lint, typecheck, test must pass before commit

hook-candidate

• Destructive command gates →

  PreToolUse

  hook returning exit code 2 to block
• Pre-commit verification →

  PreToolUse

  on git commit or

  PostToolUse

  on file Edit/Write
• Always-run-after-edit checks →

  PostToolUse

  hook

.claude/settings.json

• 6 CLAUDE.md files scanned
• 1 P0 LEAK (acme-web)
• 2 projects with drift (data-pipeline, saas-app)
• 0 over budget
• 3 projects clean

• Line 38:

  AUTH_SECRET=...

  (value redacted in report)
  • Fix: replace with

    The AUTH_SECRET env var is required; see .env.example

  • Rotate the secret in production, then

    git filter-repo --path CLAUDE.md --invert-paths

• Line 52: claims "Brevo SMTP" — code uses REST (

  @getbrevo/brevo

  at src/lib/email.ts:4)
  • Fix: change to "Brevo REST API via @getbrevo/brevo"

• "## Email" heading appears at lines 50 and 89

undefined

• Every deletion / drift finding cites the rule it enforces (R1–R10 in improve; specific drift type in audit)
• Every addition uses real project data (read

  package.json

  ,

  pyproject.toml

  , etc.) — not generic placeholders
• Every rewrite provides a concrete replacement, not "make this clearer"
• No proposal uses "consider", "perhaps", "you might want to" — every suggestion is concrete and accept/reject-able
• Summaries contain exact counts, not estimates
• P0 LEAK findings always present before any other audit content (audit mode)

• Do not auto-apply. Always present for approval. Surgical Edits only — never whole-file Write.
• Do not invent project context. Read

  package.json

  /

  pyproject.toml

  /

  Cargo.toml

  /

  Gemfile

  /

  README.md

  to ground suggestions in actual project data.
• Do not propose splitting into

  .claude/rules/

  automatically. Suggest it; the user decides.
• Do not rotate secrets or scrub git history. Audit reports leaks and guides; user drives the rotation + history scrub.
• Do not enforce a specific style across repos. Each repo's existing voice is respected. Improve mode rewrites for STRUCTURE, not VOICE.
• Do not flag perfectly fine lines. A line that fails the removability test must actually fail it — not "could maybe be tighter."
• Do not add a rule on first occurrence of a mistake. Log it in MEMORY.md or a scratch list. Promote to CLAUDE.md only after the second occurrence. Improves signal-to-noise; cuts noise rules that bloat the file without preventing real mistakes. (Source: Redreamality, April 2026.)
• Do not hardcode user paths. Use

  $TARGET

  ,

  $HOME

  ,

  $1

  . Never

  /Users/<name>/...

  .

skillforge optimize

• AGENTS.md support — audit/improve the cross-agent standard, not just CLAUDE.md; flag CLAUDE.md/AGENTS.md duplication and recommend one-source-of-truth.
• "Never auto-generate" anti-pattern with the controlled-study evidence (curated +4pp vs auto-generated −0.5–2% / +20–23% cost). Strengthens the existing trim-not-add doctrine.
• Outcome target: the skill now improves the file that actually changes agent behavior across harnesses, and actively prevents the bloat that degrades it. Sources: AGENTS.md efficiency study (arXiv 2026); agents.md standard; Augment Code AGENTS.md guide.

• How Claude remembers your project
• Claude Code Best Practices
• How Anthropic teams use Claude Code (PDF)
• Claude Code Advanced Patterns (PDF)

• HumanLayer — Writing a Good CLAUDE.md
• zodchiii — The CLAUDE.md File That 10x'd My Output (1.3M views)
• abhishekray07/claude-md-templates
• Augment Code — Karpathy skills on OpenClaw (April 2026) — empirical counterevidence: Claude Code quality regressed −0.07 when Karpathy rules were layered on top of an already-aligned system prompt.
• Fraser — Claude.md Setup Tips That Will 10x Your Claude Code Workflow (Medium, May 2026) — Karpathy's 4 rules + 8 additions, including CLI-redundancy avoidance and in-file priority ordering.
• "Dep" (@0xdepressionn) — Karpathy CLAUDE.md rule compilation (X, May 2026) — viral 14-rule set (7 communication + 7 behavior/safety) expanding Karpathy's 4 behaviors; feeds the high-impact-lines menu above. ⚠️ Headline stats (82k stars, 65%→94% accuracy, $/week figures) are unsourced marketing — the rule wording is the value, the numbers are not citable.
• Redreamality — CLAUDE.md and AGENTS.md, In Depth (April 2026) — second-occurrence promotion rule; ~80% advisory ceiling synthesis.

• Strunk & White — The Elements of Style — Rule 17 ("Omit needless words") is the upstream principle behind Anthropic's removability test

bash tests/eval.sh

1. Improve:

   /claude-md improve

   in any project — verify rubric scorecard cites every R1–R10, every change cites its rule, "no" reply writes nothing, "yes" applies surgically
2. Audit:

   /claude-md audit all

   — verify P0 LEAK section appears first when leaks present, drift findings cite specific code locations, instruction budget reported per file
3. Auto-detect:

   /claude-md

   (no args) in a project with CLAUDE.md → improve runs; in

   ~/

   with no local file → audit runs
4. Mode override:

   /claude-md audit ./CLAUDE.md

   → single-file audit (subset of audit, single target)