--- name: felhom-doc-authoring description: How to write a document that an AI agent consumes — a SKILL.md, a CLAUDE.md, a .claude/rules/ file, or a TASK spec. Triggers - creating or editing any SKILL.md; editing a CLAUDE.md or anything under .claude/rules/; writing or revising a TASK-*.md; and the phrases "write a skill", "update the instructions", "add a rule". Contains the pointer rule, the two costs, where material sits, completion criteria, sprawl, and the one-rule-one-home rule. --- # Authoring documents an agent reads A document a person reads can be skimmed and re-read. A document an agent reads is either reached or it is not, and if it is reached it is read once. That difference drives everything below. ## 1. The pointer decides everything A skill's `description`, or a line in a `CLAUDE.md` naming a document, is a **pointer**. Its **wording**, not its target, decides whether the agent reaches the material and how reliably. A must-have document behind a vaguely worded pointer is a **reliability defect**, not a documentation preference. Sharpen the wording first. Inline the material only if sharpening fails. A pointer does two jobs: 1. **Say what the material is** — the domain, in the reader's terms. 2. **List the distinct cases that should trigger reaching it** — one trigger per case. Two synonyms for the same case are one case written twice, and they buy nothing. House shape for a Felhom skill, taken from `skills/felhom-testing/SKILL.md`: a `description` that states the domain, then `Triggers - `, then one sentence naming what the skill contains. ## 2. The two costs - **Always-loaded material costs context on every turn**, whether it fires or not. A `CLAUDE.md` line is paid for in every session that opens the repo. - **Material behind a pointer costs only the pointer's own line** until it fires. - **The second cost is the human's**: knowing which documents exist and when to reach for each. Ten well-scoped documents nobody can name are worse than four that are known. ## 3. Where a piece of material sits Three rungs, ordered by how immediately the material is needed: 1. **Inline, in the ordered steps the agent performs** — what every path through the task needs. 2. **Reference in the same file, consulted on demand** — what most paths need, but not at step 1. 3. **Reference in a separate file, behind a pointer** — what only some paths reach. Inline what every path needs. Push out what only some paths reach. Getting this wrong in either direction is a cost: rung 1 material on rung 3 gets missed; rung 3 material on rung 1 is paid for every time and dilutes the steps around it. ## 4. Completion criteria **Every step ends on a condition that says it is done.** "Investigate the failure" has no bound; "name one command that reproduces it, and show its output" does. A vague bound invites stopping early, and stopping early looks identical to finishing. When a step feels too large, **sharpen the bound before you consider splitting the step** — most oversized steps are underspecified, not overloaded. ## 5. Sprawl and co-location A document can be too long even when every line in it is live. Attention thins across the excess, and the lines that matter most are not the ones that survive. **Felhom's limit: a `SKILL.md` is under 150 lines.** If one will not fit, say so and stop — do not silently split it into two documents nobody knows how to choose between. **Co-locate.** Keep a concept's definition, its rules and its caveats under one heading. A concept scattered across four sections is four chances to read three of them. ## 6. One rule, one home If a rule already lives in another skill, or in `documentation/runbooks/workspace-CLAUDE.md`, **point at it by name and give only your additional material.** Two copies of a rule drift. When they do, the reader cannot tell which is current, and the safest reading — obey both — is not always possible. This is why `felhom-diagnosis` points at `felhom-testing` for the red-proof instead of restating it, and why `felhom-evidence` cites standing rules 2 and 3 in one line each rather than lifting them across. ## 7. Validate it `python3 scripts/check_skills.py` (in `felhom.eu`) checks every `skills/*/SKILL.md`: the frontmatter parses, `name` matches the directory, `description` and the body are non-empty, the file is under 150 lines, and any installed copy under `~/.claude/skills/` still resolves back into the repo. Installation is `python3 scripts/install_skills.py`. It discovers skills by globbing `skills/*/SKILL.md`, so **a new directory needs no registration** — the glob is the registry. Do not add a manifest or an index.