authoring

# Authoring A skill is a document an agent executes, not prose a human skims. Reference only; the edit belongs to whoever called you. Before writing a new one, run the skill-audit search pass: consolidation is the house default and a near-duplicate is a revision, not a new directory. ## The contract A shipped skill is one top-level directory holding `SKILL.md` at its root, `agents/openai.yaml`, and optional `references/*.md`. Nesting hides it from the installer; an empty directory fails the gate. Frontmatter carries exactly four keys, in order, and nothing else: ```yaml --- name: <directory name, lowercase kebab> description: "<one quoted sentence naming the workflow and its deliverable>" category: <the enum this skill belongs to> mutates: <none | documents | repo | external> --- ``` `name` must equal the directory name character for character. `description` is the pointer the runtime reads to decide whether to load you, so it front-loads the verb and names the outcome; it is the only always-loaded line you own, and every word costs on every turn. `mutates` is a promise the body has to keep. `none` means read-only. `documents` means it writes under the repository's own notes and wish tree. `repo` means source edits. `external` means it reaches a network or another host. ## House size Forty to ninety lines. Under forty and the skill is a paragraph wearing a directory; over ninety and attention thins across the excess. When a skill outgrows the ceiling, push the on-dem...