A CLAUDE.md That Earns Its Tokens

What it is for

A CLAUDE.md is read on every request, so everything in it is paid for repeatedly. The test for a line is whether the agent would get something wrong without it; anything that only reassures a human reader is costing tokens and crowding out what matters.

The skill Copy

CLAUDE.md is loaded into every conversation in the project. That is a standing
cost, so every line has to pay for itself.

The test for a line: **would the agent get this wrong without it?**

Include:
- **Commands that are not guessable.** The real test command, the real build
  command, the flag that is always needed. Not `npm test` if that is what it
  obviously is.
- **Conventions the code does not make obvious.** "Money is always stored in
  the smallest unit." "Never import from `internal/` outside its package."
- **Traps with their symptom.** "The dev server caches the schema; a migration
  needs a restart or you get a stale-column error that looks like a typo."
- **What NOT to touch**, and why. Generated files, vendored code, a module that
  is being replaced.

Leave out:
- Anything derivable from the code in one read. The directory layout, the
  framework, the language.
- Style rules the linter already enforces. The linter is more reliable than a
  paragraph.
- History. What the project used to be does not help with what to do now.
- Aspirations. "We aim to have full coverage" is not an instruction.

Re-read it when something goes wrong twice in the same way. That is the signal
a line is missing — and the wording of the failure is usually the line.

How to install it Copy

Claude Code / Claude Desktop

1. Create a folder named after the skill inside your skills directory:
   - Claude Code: `~/.claude/skills/<skill-name>/`
   - A project-local skill: `<project>/.claude/skills/<skill-name>/`
2. Save the text below as `SKILL.md` in that folder, keeping the
   `---` frontmatter block at the top — the `name` and `description`
   fields are what make the skill discoverable.
3. Restart Claude Code, or run `/skills` to confirm it is listed.

The skill loads only when its `description` matches what you are doing,
so a precise description matters more than a long body.

Did it work for you?

Where it came from