Anatomy of a skill

A skill is the smallest reusable unit the engine knows how to execute. Everything the engine needs to run one - which model to call, which tools to expose, how many tool-calling iterations to allow, and what the system prompt should be - is captured in two files that live next to each other in the source tree. There is no plugin loader, no database lookup, no runtime registration. The catalog is closed by design.

The contract is also tiny. One TypeScript interface, one filename convention, one always-on tool set. Anyone who has read this page once can scan an unfamiliar skill in under a minute and know what it does, what it touches, and what it cannot do.

The category determines two things. First, the folder a skill's SKILL.md is loaded from at runtime. Second, the group the catalog browser shows the skill under. The two stay in sync because the loader composes the file path from the category string itself.

The runtime preference order is intentional. For values that change behavior (tools, model, maxTurns, category), the manifest is the source of truth and the loader ignores whatever the frontmatter says. For human-facing strings (name, description), the frontmatter wins so a maintainer can edit the markdown file without touching the registry.

Skill bodies follow a loose template across the catalog. A short persona statement at the top, a Before Starting checklist that lists prerequisites and memory lookups, one or more numbered Mode sections describing the actual procedures, an output format spec, and a quality gate. The model reads the entire body on every invocation; long bodies mean expensive turns, so most skills stay under a thousand tokens.

The discovery model only sees the description, not the body. If the description tries to describe what the skill does, the discovery model will start to follow the description and skip reading the full prompt. Keep descriptions to a single sentence focused on the trigger condition. Include the exact words a user is likely to type. List sibling skills the description should rule out.

Pick the fastest class for tight extract-and-format work that does not require deliberation. Pick the default class for the agentic loop where the model picks tools and synthesizes results. Pick the heaviest class for long planning sessions, document scanning, or skills that have to compose more than five tool calls deep.

The turn budget is the wider lever. A six-turn budget keeps a skill snappy and predictable. A twelve-turn budget lets a skill recover from missed searches and re-plan once. Bigger than twelve is almost always a sign the skill should be split into two.