A Claude Code skill · open source

agent-guides

A cold agent, or a new teammate, should read under 3k tokens before a safe change anywhere in the codebase: the root guide, plus the guide of the folder it works in.

Most repos grow one long CLAUDE.md that every session loads, half of it about folders the session never opens, some of it no longer true. agent-guides moves each fact to the folder it governs, generates what the code already knows, and adds tests that fail when a guide goes stale.

/plugin marketplace add khairold/skills
/plugin install khairold@khairold
/khairold:agent-guides

Part of khairold/skills, with dot-plan and codebase-audit. MIT licensed.

The idea in four lines

The code is the first source. A guide says only what reading the code would not tell you quickly: the purpose, the public surface, the rules that must hold, the tests that prove them.
One fact, one place. In the guide of the folder it governs, in a list the code reads, or in a generated block. Everywhere else points at it.
What the code knows is generated. Tables, routes, commands, jobs, env vars, who imports whom. A test fails when the committed block is stale.
Present tense only. Guides and comments say what is true now. History goes to the decision log and the commit messages.

Modes

default

`/agent-guides`

The whole codebase. Surveys it, proposes one screen of changes, then writes the guides, the generator and the tests.

You confirm once

scoped

`/agent-guides <path>`

One folder's guide and its generated block. Problems found elsewhere are listed, not fixed.

You confirm once

report

`--check`

The survey and the proposal as a report. Writes nothing.

You read it

The run

Survey. Map the codebase into units, list every guidance file and what it claims, find build notes in comments, and count the tokens a cold agent reads today.
Propose, then wait. One screen: the guides to write, what leaves the root guide and where it goes, what the generator will produce, the tests, the cold read now and after. Nothing is written before you confirm.
Write the guides, one per unit, and cut the root guide to what the project is, where to look, the loop and your hard rules. At most 80 lines.
Add the generator and the tests to your repo, in your language and your test suite.
Prune the agent's memory of lines that name moved paths or repeat what a guide now holds.
Verify with your own checks, measure the cold read again, and report.

Every claim gets a mark

The survey reads each line of guidance and decides where it belongs.

Mark	Meaning	Goes
`keep`	true, needed in every session, in the right file	stays
`move`	true, but governs one folder	that folder's guide
`point`	true, but a doc already holds it	a one-line pointer
`generate`	true, and the code already knows it	the generator
`dup`	said in two places	the one place it belongs
`stale`	names a path, command or behaviour that is gone	fixed or deleted
`history`	why it used to be, a plan step, a done migration	the decision log

A folder guide

Short: under about a thousand tokens plus its generated block. Claude Code loads a folder's CLAUDE.md by itself when a file there is read, so the agent gets it exactly when it needs it.

# path/to/unit

What this unit is for, in two lines at most.

## Public surface
- `file`: `name` (what a caller uses it for)

## Invariants (each held by the test named)
- Only `trail` writes the audit table: `tests/test_borders.py::test_only_the_trail_writes`

## Tests to run for a change here
- `pytest tests/unit/trail` then the full check

## Read more
- Why: the decision log, D-42

<!-- generated by scripts/build_guides.py: do not edit -->
## Owns (generated)
tables, routes, commands, jobs
<!-- end generated -->

An invariant names its test. A rule no test holds is marked (not tested) and listed in the report.

What keeps it true

The tests go in your own suite, so a stale guide fails in the same place as a broken build, with a message that tells the agent what to do.

Test	Fails when	Says
guides are current	a generated block differs from what the generator would write	run the generator
guide paths exist	a guide names a path that does not exist	fix the guide
guide commands exist	a guide names a command, script or target that does not exist	fix the guide
every unit has a guide	an app or package has no guide	write its guide
the root guide stays short	the root guide passes 80 lines	move a fact to its folder's guide
code carries no build notes	a comment says "step 4", a plan item or "was X before"	say what the code does now

Where it came from

The last phase of an agent-run refactor of a Django monolith. The root guide had grown to 141 lines that every session loaded, and an audit of it found claims about paths that no longer existed, facts said in three places, and build steps left in code comments.

After the phase: eleven app guides plus one each for the tests and the database, a root guide of 75 lines, and a cold read of about 2.7k tokens for the largest app. A generator writes each guide's inventory from the code, and the test suite fails when one goes stale. The phase became this skill.