version: "1.0.0" name: skill-authoring description: "Writing and improving agent skills: description as routing signal, progressive disclosure, token budgets, testing before shipping, and improving from repeated mistakes. Use when authoring, editing, or reviewing a skill."

Skill authoring

A skill is instructions that route: the description selects it, the body runs it. Write for both, and test before shipping.

Structure

• SKILL.md frontmatter: name (kebab-case, equal to the directory name) and description. Flags and loading rules: guide://extensions.
• Body: the procedure, imperative, in the fewest lines that stay complete. Lead with the steps; put the why in one clause where a step would look arbitrary without it.
• References (references/*.md, at most 3): deeper material only some tasks need. The body must stand alone without them. Template: references/template.md.
• Budgets: description 220 characters or less; body 120 lines and about 6 KB or less. Every session lists the description, so cut hard.

The description is the routing signal

• It is the only text seen before a skill is read. It must contain the task vocabulary a user would actually type.
• Third person, one or two sentences: what the skill does, then "Use when ..." for the trigger.
• Test it: write three prompts that should select the skill and two that should not. If the description cannot separate them, rewrite it.

Body rules

• Imperative voice; checklists and tables over prose.
• Add a red-flags section wherever the failure mode is an agent rationalising a shortcut; those are the costly failures.
• State constraints where they matter ("never install a browser engine", budgets, portability rules).
• Do not restate what the model already knows, and do not duplicate agent role instructions; skills are shared knowledge, roles are assignments.

Test before shipping

• Dry-run: hand the skill and a realistic task to a fresh agent context; watch whether the procedure is followable as written. Ambiguity shows up as invented steps.
• Pilot prompts: selection fires on the should-list and stays quiet on the should-not-list.
• Budget check: measure description characters, body lines, and bytes mechanically after every edit.

Improvement loop

Fix a repeated mistake at the HIGHEST enforceable level: lint, then test, then prose. A rule in tooling cannot be forgotten; a rule in prose can.

Keep a rule-to-enforcement table in the skill when several rules exist; anything enforced below its level is a known gap, not a fix.

Where skills live

• Roots, discovery order, and precedence: guide://skills.
• Format mechanics: guide://extensions. Template to copy: references/template.md.