skill-author: grow the library deliberately, or not at all
The studied failure mode is real: a library of 557 imported skills with 3 in use. Skills are context spent on every session's listing. Each one must earn that. The general rule this ladder instances - every addition declares where it is paid, and the always-on surface carries the highest bar - is decision 0015.
1. Should this be a skill? (ladder: stop at the first rung)
- One-off knowledge? Put it in the task, not the library.
- A durable fact or rule? It belongs in the owning doc (
docs/standards/, DESIGN.md, AGENTS.md if truly universal), not a skill. - Mechanically checkable? Add a check to
checks/check.mjs+ a fixture test. Never send a model to do a linter's job. - Recurring method requiring judgment (a way of working you'd teach a new senior hire) → that is a skill. The trigger: you've needed it three times, or you know you will.
2. Write it
Create .agents/skills/<name>/SKILL.md (open Agent Skills standard):
- Frontmatter:
name= directory name (lowercase, hyphens, ≤64 chars);description≤1024 chars stating what it does and when to load it. Write the trigger phrases the moment of need actually contains; this line is all the model sees when deciding to load it. - Body ≤500 lines, imperative, information-dense. Structure: purpose (one line) → the method (numbered, decision points explicit; ladders beat essays) → what to record → how it relates to the automated gates (judgment layer above, never duplicate of).
- Heavy reference material goes in files next to SKILL.md, linked one level deep, loaded only when needed. No code snippets that will go stale: point at the living source instead.
- End the body's report instruction with the ⚓ convention if the skill produces user output.
3. Register and validate
- Add one row to the skills table in
AGENTS.md(keep the ≤150-line budget: if it doesn't fit, something else must leave; that trade-off is the point). - Run
node checks/check.mjs. It validates frontmatter, name/dir match, and budgets. - Test the trigger: describe the situation to a fresh session and confirm the skill loads.
4. Maintain
Skills decay in three ways: sediment (steps that stopped being needed but never left),
sprawl (one skill quietly absorbing a second job: split it), and no-ops (rules so vague
no behavior would change: sharpen or delete). After using a skill, reread it and prune what
decayed in that same session. The skills table in AGENTS.md is the library's router: every
skill earns its row by being findable from its moment of need, and a skill nobody has loaded in
months is a candidate for deletion. Check before big milestones. Deleting a wrong or dead skill
is maintenance, not loss; note it in STATE.md's log. ⚓