Skill Author

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)

1. One-off knowledge? Put it in the task, not the library.
2. A durable fact or rule? It belongs in the owning doc (docs/standards/, DESIGN.md, AGENTS.md if truly universal), not a skill.
3. Mechanically checkable? Add a check to checks/check.mjs + a fixture test. Never send a model to do a linter's job.
4. 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. ⚓