admin
c30430c530
The four existing skills cover the product; nothing covered how work is reported. Two rules this project has paid for — check the artifact rather than the report, and do not state a claim more firmly than the evidence allows — lived only in the operator's head and in chat, where Claude Code never read them. - felhom-evidence five confidence tiers, artifact-over-report - felhom-diagnosis no hypothesis until a command has been seen red - felhom-plain-language ASD-STE100, two options, the re-pitch - felhom-handoff the note goes to a FILE, not the conversation - felhom-doc-authoring the pointer decides whether material is reached scripts/check_skills.py asserts what decides whether a skill is EVER reached: frontmatter parses, name == directory, description and body non-empty, under 150 lines, installed copy still samefile()s into the repo. install_skills.py globs and never reads the file, so a missing description installs perfectly and then silently never loads. It convicted on its first run: felhom-build-deploy is 179 lines. NOT trimmed here (pre-existing skills are out of scope, and trimming a deploy skill without exercising its commands is how a wrong command reaches a live host) — a named single-entry GRANDFATHERED exception, WARNed every run, R-394. A new skill over the limit is convicted. Red-proof run and seen failing: description removed from felhom-evidence -> exit 1, "frontmatter field 'description' is missing or empty". Restored, tree clean. skills/SOURCES.md records both MIT upstreams, that these are adaptations not copies, and the six pieces deliberately EXCLUDED with reasons. Register: R-392 (no architecture doc covers the two-AI workflow), R-393 (decision-log skill deferred, with the reason), R-394.
4.6 KiB
name, description
| name | description |
|---|---|
| felhom-doc-authoring | 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:
- Say what the material is — the domain, in the reader's terms.
- 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 - <comma list>, 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.mdline 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:
- Inline, in the ordered steps the agent performs — what every path through the task needs.
- Reference in the same file, consulted on demand — what most paths need, but not at step 1.
- 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.