context-file-tuneup · git:20260523.7ad65ae · 2026-05-23 · sha256 76b3c5f91c27eb35

context-file-tuneup git:20260523.7ad65aeB

Immutable. This exact content never changes and is served at /api/v1/blob/76b3c5f91c27eb35.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_za5y2d6keoq2onfl/76b3c5f91c27eb353cefd3f34f80f4c579b694b8596f399231ada8d6a1b91c34.json

Then /plugin install context-file-tuneup@markdownregistry-za5y2d6keoq2onfl in Claude Code. It installs this exact version, the one graded B here, pinned to the commit it was graded at, and leaves it there.

---
name: context-file-tuneup
description:
  Audit, rewrite, and tighten a CLAUDE.md / AGENTS.md file so it actually helps
  a coding agent instead of bloating its context. Use this skill whenever the
  user wants to review, clean up, fix, shrink, restructure, or improve a
  CLAUDE.md / AGENTS.md file
---

# Context File Tune-up

A `CLAUDE.md` or `AGENTS.md` file is loaded into the agent's context on every
task. That makes it the highest-leverage and most-abused file in a repo: a good
one silently prevents whole classes of mistakes; a bloated or vague one wastes
the context budget and gets ignored. This skill audits an existing CLAUDE.md /
AGENTS.md against a known-good structure, derives what it _should_ contain by
inspecting the repo, proposes a full rewrite, and applies it only after the user
confirms.

The core loop is **inspect → audit → propose → confirm → apply**. Never skip the
confirm step — this file encodes human judgment about a codebase, so the user
gets the final say before anything is written.

## What "good" looks like

Internalize this target before auditing anything. A great context file is
**short, specific, and verifiable**. The enemy is generic advice the model
already knows ("write clean code", "follow best practices") — it costs tokens
and teaches nothing.

**Hard length budget: ~300 lines.** If the content genuinely needs more, that is
a signal to extract a `rules/` directory and leave behind a _router_ — a few
lines in the main file telling the agent which rule file to read for which task
(see "The rules-router pattern" below). A 1,000-line CLAUDE.md is worse than
useless; the agent skims it.

**Ideal section order** (omit any section that has nothing real to say — empty
scaffolding is noise):

1. **One-liner** — what the project is and its motivation/direction, in a
   sentence or two. Orients everything else.
2. **Non-obvious tooling / settings / version quirks** — the package manager
   that isn't the default, the required env var, the Node version that breaks
   the build, the lockfile that must not be regenerated.
3. **Concise architectural map** — only what isn't obvious and would otherwise
   take reading several files to discover. Where the entry point is, how the
   major pieces talk, where the surprising boundary sits. Not a file-by-file
   tour.
4. **Rules with verifiable instructions** — each rule should be checkable.
   "Parameterize all SQL" not "write safe database code". "Run `pnpm typecheck`
   before committing" not "make sure types are correct".
5. **Hard constraints / anti-patterns** — the bright lines. "Never edit files in
   `generated/`." "Do not add dependencies without asking." "Never call the prod
   API from tests."
6. **Pointers to deeper docs** — link out instead of inlining.
   `See docs/deployment.md for the release process.`
7. **Gotchas / tribal knowledge** — the load-bearing weirdness. "The retry logic
   looks broken but is intentional — see PR #123." "`utils/legacy.ts` is dead
   code we can't delete yet because of X." This is the highest-value,
   hardest-to-recover content and almost never lives in the code itself.

A line earns its place only if it changes what the agent does. If removing a
line would not cause a single mistake, it is probably noise.

## Workflow

### Step 1 — Locate and read the file

Find the target. Check the repo root and common locations: `CLAUDE.md`,
`.claude/CLAUDE.md`. If the user named a path, use it. If none exists and the
user wants one, jump to "Creating from scratch".

Read the full file. Count its lines — you will reference the number in the
audit.

### Step 2 — Inspect the repo for ground truth

Do not audit in a vacuum. Spend a few minutes deriving what the file _should_
contain so you can spot what's missing, stale, or wrong. Cheap, high-signal
things to check:

- **Manifests / lockfiles** — `package.json`, `pyproject.toml`, `Cargo.toml`,
  `go.mod`, `Gemfile`. Reveal the real package manager, scripts
  (test/lint/build/typecheck), language version, and key dependencies.
- **Tooling config** — `Makefile`, `justfile`, `.tool-versions`, `.nvmrc`, CI
  workflows in `.github/workflows/`. CI is gold: it shows the _actually
  enforced_ checks, which are the rules worth stating.
- **Structure** — top-level directory layout (2 levels deep is plenty). Identify
  the entry point and the major modules.
- **Existing docs** — a `docs/` folder, `README.md`, `CONTRIBUTING.md`. These
  are pointer targets, and sometimes content has been duplicated into the
  context file that should just be a link.
- **Tribal-knowledge signals** — gotchas usually aren't in the manifest, but
  they leave fingerprints in the repo. Grep code comments for markers like
  `HACK`, `XXX`, `FIXME`, `do not remove`, `do not edit`, `load-bearing`,
  `intentional`, `workaround`, `gotcha`. Skim recent git history
  (`git log --oneline -50`) and look for commit messages or PR references that
  explain surprising decisions ("revert", "actually needed", "fixes flaky").
  These are candidates for the gotchas section — surface them in the audit
  rather than inventing gotchas from nothing.

Note discrepancies as you go: scripts the file mentions that don't exist, a Node
version that disagrees with `.nvmrc`, rules that contradict the CI config.

Keep this proportional. A quick scan is the goal, not an exhaustive code review.
If the repo is huge, sample the most relevant areas rather than reading
everything.

### Step 3 — Produce the audit

Present a structured audit before proposing any change. Lead with the headline
numbers, then go section by section. Use this shape:

```
## Audit: CLAUDE.md (<N> lines)

**Verdict:** <one line — e.g. "Solid bones, ~40% is generic filler, missing the gotchas section.">

**Length:** <N> lines vs ~300 target. <If over: what to cut or extract.>

**Section coverage:**
- ✅ One-liner — present and clear
- ⚠️ Tooling — mentions pnpm but omits the required NODE_OPTIONS env var (found in CI)
- ❌ Architectural map — absent; the worker/api split would take 4 files to discover
- ⚠️ Rules — present but vague ("write good tests" → unverifiable)
- ❌ Gotchas — absent

**Specific problems:**
1. Lines 12–28: generic advice the model already knows. Cut.
2. Line 34: references `npm run build`, but package.json uses pnpm and the script is `build:prod`. Stale.
3. ...
```

Be concrete and cite line numbers and evidence (especially repo evidence — "CI
runs `ruff check`, but the file says nothing about linting"). Praise what's
good; don't rewrite working sections for the sake of it. The point is signal,
not a full demolition.

### Step 4 — Derive the gotchas section from the repo

Tribal knowledge — the _why_ behind load-bearing weirdness — is the
highest-value content and the hardest to recover. Don't ask the user for it;
derive it from the signals gathered in Step 2 (comment markers, git history, PR
references). For each candidate, write a gotcha note that states the surprising
thing, why it exists, and a pointer to the evidence — e.g. "The retry logic in
`dispatch.ts` swallows the first failure on purpose; see commit a1b2c3d / PR
#123."

If the repo yields no real tribal-knowledge signal, leave the gotchas section
out entirely rather than padding it with guesses. An empty section is worse than
no section. (If the user volunteers a gotcha in conversation, fold it in — just
don't interrogate them for it.)

### Step 5 — Propose the full rewrite

Show the complete rewritten CLAUDE.md in a code block — the whole file, ready to
drop in, not a diff or a partial. Precede it with a short summary (a few lines)
of the major moves you made so the user can orient quickly: what you cut, what
you added, the new line count. The rewrite is the thing they're approving; the
summary is just a map of it.

```
Here's the rewrite. Major moves:
- Cut the generic-advice and React paragraphs (filler the model already knows)
- Fixed the stale commands (npm → pnpm, build → build:prod)
- Added an architectural map (api ↔ worker via Redis queue) and the enforced CI checks
- Added a gotchas section from the "do not remove" notes in dispatch.ts
- 142 → 96 lines

<full rewritten file in a code block>
```

For a file being split into a `rules/` directory, show the rewritten main file
(with the router) plus each new `rules/*.md` file in full.

End by asking for confirmation: approve as-is, or tell you what to change. Treat
any pushback as input for another pass — re-propose, don't argue.

### Step 6 — Apply on confirmation

Only after explicit approval, write the rewritten file to disk. If splitting
into a `rules/` directory, create it and write the router into the main file.
Confirm what was written and the final line count. If the user asked for
feedback instead of approval, fold it in and re-present — back to Step 5.

## The rules-router pattern

When content legitimately exceeds ~300 lines, don't cram. Extract topic files
and leave a router. The main file stays a fast index; the agent reads a rule
file only when the task calls for it.

```
CLAUDE.md            ← stays lean; one-liner, tooling, map, hard constraints, + the router
rules/
  testing.md         ← detailed testing conventions
  database.md        ← schema rules, migration process, SQL conventions
  frontend.md        ← component patterns, styling system
```

The router lives in the main file and reads like:

```markdown
## Detailed rules — read the relevant file before working in that area

- Writing or changing tests → read `rules/testing.md`
- Touching the database, schema, or migrations → read `rules/database.md`
- Frontend components or styling → read `rules/frontend.md`
```

The trigger condition ("when working on X") is the important part — without it
the agent doesn't know when to pull the file in. Each extracted file should
itself respect the spirit of the budget: focused and verifiable.

## Creating from scratch

If no file exists and the user wants one, run Step 2 (inspect) and Step 4
(derive gotchas from the repo) to gather material, then draft directly into the
ideal structure and confirm before writing. Start minimal — it is far better to
ship a tight 60-line file the team will extend than a speculative 300-line one
full of guesses. Only include sections you have real content for.

## Reference

For a richer set of before/after examples — vague rules rewritten as verifiable
ones, filler that should be cut, good gotcha notes — read
`references/examples.md`. Pull it in when you want concrete patterns to model
the rewrite on or to show the user.