MadAppGang Authoring a skill in this repo
A skill exists to give an agent procedural knowledge it would not reliably reproduce on its own. It has exactly two jobs, and they are separate:
| Part | Job | Read by |
|---|---|---|
description |
decide whether to load | every turn, for every installed skill |
SKILL.md body |
do the task correctly once loaded | only after it triggers |
The description is the only part with an always-on cost. Everything else is pay-as-you-go.
The one path
- Write the description (below). It is the highest-leverage text in the skill.
- Write the body: objective, inputs and outputs, the ordered workflow, decision points, failure modes, verification. One recommended path, imperative voice.
- Move conditional depth into
references/, each with an explicit loading instruction. - Choose the visibility. Read
references/visibility.md— this is where skills break. - Run
bun skills/skill-authoring/scripts/check-skill.ts <path>. Fix what it reports. - If the skill must trigger reliably, run the routing evaluation in
references/routing-eval.md.
The description
Capability first. Over budget, Claude Code shortens descriptions rather than dropping skills, so the tail is what disappears. Lead with what the skill does, not when.
<what it does, concretely>. Use when <intent, artifacts, phrasings a user actually types>.
Do not use for <the nearest sibling that competes>; use <that skill> instead.
The boundary clause is optional and costs characters. Add it only where a sibling genuinely competes for the same words. Two in a plugin is normal; five means the skills themselves overlap and the fix is a merge, not more prose.
Be slightly pushy. Models under-trigger. An "even if they only say X" clause catches indirect phrasing, and it earns its characters on disciplines nobody names out loud — nobody types "apply verification-before-completion".
Ceiling: 250 characters. This repo's limit, enforced by
scripts/skill-budget-check.ts in CI, and stricter than the portable 1,024. It is a
ratchet: lower it as descriptions improve, never raise it to make a build pass.
Never put in a description:
- Workflow steps. A description that summarises the procedure gets followed instead of the body. One skill in the wild performed one review instead of two because its description said "review between tasks" while its body specified two passes.
- Vague filler — "Helps with documents", "Processes data". The commonest reason a skill never fires.
- Keyword lists. The matcher is plain-text injection; words already in the sentence work, and a trailing list is pure cost.
<or>. They fail validation.- Anything the skill cannot actually do.
Only these frontmatter keys are read: name, description, when_to_use,
argument-hint, arguments, disable-model-invocation, user-invocable,
allowed-tools, model, effort, context, agent, hooks, paths, shell.
triggers:, tags: and keywords: are silently ignored — a skill relying on them
has no triggers at all.
Visibility
Three states, and the choice is not about tidiness — it decides whether consumers keep working.
| State | Frontmatter | Costs budget | Reachable by |
|---|---|---|---|
| listed | (nothing) | yes, every turn | the model, on its own judgement |
| hidden | disable-model-invocation: true |
no | name, or a router that says read this file |
| slash-only | user-invocable: false |
yes — saves nothing | the model; hidden from the / menu |
disable-model-invocation: true does two things. It removes the skill from the
listing and blocks preloading into subagents. An agent or command naming the skill in
its skills: frontmatter has that content injected automatically; hiding the skill
silently starves that consumer while every gate stays green.
Before hiding anything, check who preloads it:
bun scripts/dev-skill-inventory.ts <plugin> # the `preloaded by` column
If it has consumers, the same change must give each of them the content another way.
Full decision table and the preload/read trade-off: references/visibility.md.
Routers, not listings
A plugin with many skills lists one router and hides the rest. The router's body is a table of files to open.
Write "read this file", never "invoke this skill". Measured in benches/skill-index/
(IDX-1): the Skill-tool phrasing was ignored — the tool never fired, even when a prompt
named the skill directly. The file-read phrasing produced the skill being used. A row
that prescribes an action the reader cannot take teaches nothing.
Working examples in this repo: bunjs:bun (9 skills, 8 hidden, 187 chars) and
dev:context-detection.
The body
Carry what is needed on most invocations: objective and success criteria, required inputs and outputs, the ordered workflow, decision points, safety boundaries, non-obvious failure modes, verification checks, one short example, and a map of when to open each reference.
Under 500 lines and ~5,000 tokens — ceilings, not targets. Cut anything the base model already knows. Prefer one recommended path; offer alternatives only where the reader genuinely must choose.
references/ holds conditional depth, and every reference needs an explicit loading
instruction: "Read references/aws.md only when the target provider is AWS." A
reference nobody is told to open is maintenance with no reader. scripts/ holds
deterministic work — validation, transformation, fragile command sequences — and runs
without its source entering context. assets/ holds templates to copy.
Do not ship README.md, CHANGELOG.md, QUICK_REFERENCE.md, authoring notes or
evaluation workspaces inside a skill. They are not instructions.
Fixing by symptom
| Symptom | Fix |
|---|---|
| never fires | lead with what it does; add the exact phrasings users type |
| fires for the wrong thing | add specificity, or one boundary clause naming the sibling |
| fires, output wrong | the body is wrong. Do not touch the description |
| fires only when named | it is hidden, or the listing is over budget and it got shortened |
| a subagent lost its guidance | something was hidden while that agent still preloaded it |
Before reporting done
bun skills/skill-authoring/scripts/check-skill.ts <skill-dir> # mechanical
bun scripts/skill-budget-check.ts # ceilings
bun scripts/dev-skill-inventory.ts <plugin> # nothing hidden is preloaded
A skill is not finished because it exists. It is finished when it triggers on the prompts it should, stays quiet on the ones it should not, and no consumer lost anything.