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:

---
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-demand half into references/ under the skill's own directory and point at it by a skill-relative path. Inline what every branch needs; disclose what only some branches reach.

Voice

• Write runtime-neutral. Name the runtime's native delegation surface, never one vendor's tool name or one host's directory layout.
• Reference other skills by name in prose, as "the review skill", never as a path into another skill's directory. Cross-directory paths break the moment the installer lands the tree somewhere else.
• Resolve every shipped file relative to the loaded SKILL.md. A repository root or a host environment variable is not available to an installed skill.
• Prompt the positive. A prohibition drags the forbidden behaviour into context; state the target behaviour instead, and keep a ban only where no positive phrasing exists.
• Every step ends on a checkable completion criterion. "Understanding reached" invites an early exit; "the gate exits zero" does not.
• Keep each meaning in one place. The environment is a source of truth too, so a line that restates a command's help output is a cache that will go stale.