context-file-tuneup

What this skill does

# Context File Tune-up

A `CLAUDE.md` or `AGENTS.md` file is loaded into an agent's context on every
task. Different agents and repos use different filenames, and some repos keep
one as a symlink or compatibility alias to the other. Treat them as the same
class of file: high-leverage repo instructions for coding agents. A good one
silently prevents whole classes of mistakes; a bloated or vague one wastes the
context budget and gets ignored. This skill audits the target context file
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, classify, and read the target

Find the target context file before auditing. If the user named a path, use that
path. Otherwise check the repo root and common locations:

- `AGENTS.md`
- `CLAUDE.md`
- `.claude/CLAUDE.md`
- nested `AGENTS.md` files when the user is asking about a subproject or
  directory-specific context

When more than one candidate exists, identify the relationship instead of
guessing:

- Run a symlink-aware check such as `ls -l <path>` or `test -L <path>` for each
  candidate.
- If one file is a symlink to the other, treat the real target as the source of
  truth. Say so in the audit and avoid editing both paths separately.
- If both files are regular files, compare their purpose. `AGENTS.md` is often
  repo-agent routing while `CLAUDE.md` may be Claude-specific compatibility, but
  do not assume that without reading them.
- If a nested `AGENTS.md` applies to the user's requested subdirectory, audit it
  together with the nearest parent/root context file so the rewrite preserves
  the routing relationship.

Read the full target file after resolving symlinks and hierarchy. Count its
lines — you will reference the number in the audit. Also note the target type in
your audit: `AGENTS.md`, `CLAUDE.md`, nested `AGENTS.md`, symlinked alias, or
multiple independent context files.

### 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: <context-file-path> (<N> lines)

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

**Target:** <AGENTS.md / CLAUDE.md / nested AGENTS.md / symlink relationship / multiple files reviewed.>

**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 log