Building Skills

Building Skills

An agent skill is a folder with a SKILL.md file that teaches an agent a task on demand. The format is an open standard (spec) supported across many agents, so write skills that are portable, not tied to one product.

The goal every time: make the skill smaller, clearer, and more useful than before. A skill is read thousands of times but written once — every token must earn its place.

How skills load (progressive disclosure)

┌──────────────┐ always loaded ┌───────────────────────────────────────┐
│ 1. metadata  │──────────────▶│ name + description (~100 tokens)      │
└──────────────┘               │ the only input used for triggering    │
                               └───────────────────────────────────────┘
┌──────────────┐   on trigger  ┌───────────────────────────────────────┐
│ 2. SKILL.md  │──────────────▶│ body instructions (aim < 500 lines)   │
└──────────────┘               └───────────────────────────────────────┘
┌──────────────┐   as needed   ┌───────────────────────────────────────┐
│ 3. resources │──────────────▶│ scripts/, references/, assets/        │
└──────────────┘               └───────────────────────────────────────┘

Put each thing at the cheapest level that works: triggering cues in the description, the core workflow in the body, and bulky detail in resources the agent reads only when needed.

Frontmatter

YAML frontmatter, then Markdown. Only name and description are required.

Most skills need nothing beyond name, description, and license. Don't add fields speculatively.

Name

Pick the form from what the skill is about:

• A specific tool → name it after the tool: agent-browser, gh-cli, mcporter. Namespace by tool when it sharpens triggering (gh-address-comments).
• A repeatable task, workflow, or broad action → use the gerund form (verb + -ing): building-skills, writing-issues-and-prs, managing-deployments.

Either way keep it short and hyphenated, and avoid vague names like helper, utils, tools.

Description — the trigger

This is the only text the agent sees when deciding to use the skill, so it carries all the "when to use" information; never put that in the body. State what the skill does and the concrete contexts/phrases that should invoke it, and use specific keywords for discovery. When a capability summary starts with a verb, use third-person singular; use the imperative mood for instructions to the agent, including when to load the skill. Quote the value if it contains colons or other YAML-special characters.

• Good: Uses GitHub CLI (gh) for GitHub repositories, issues, pull requests, actions, releases, gists, and API calls. Use when a task requires GitHub operations from the command line.
• Poor: Helps with code. (vague, no trigger)

If a skill under-triggers, make the description a bit more assertive about its triggering contexts rather than adding rules to the body.

Core principles

• Concise is key. Assume the agent is already smart. Add only what it doesn't already know — non-obvious procedure, domain facts, project conventions. Challenge every line: does it earn its tokens? Cut introductions, summaries, and explanations of common knowledge.
• Explain the why, not just the what. A short rationale lets a capable agent generalize to cases you didn't foresee. Reframe heavy-handed ALWAYS/NEVER rules as the reasoning behind them; reserve hard constraints for genuinely fragile, error-prone steps.
• Match freedom to fragility. Open-ended task with many valid paths → high-level prose. Preferred pattern → pseudocode or a parameterized example. Fragile sequence where mistakes are costly → a precise script with few choices.
• Generalize, don't overfit. The skill must work across many future prompts, not just the example in front of you. Prefer durable patterns over special-casing.
• Write imperatively. Direct instructions to the agent ("Run X", "Read Y first"), not narration.

Anatomy

skill-name/
├── SKILL.md      # Required: frontmatter + instructions
├── scripts/      # Executable code for deterministic or repeated work
├── references/   # Docs the agent reads on demand (schemas, APIs, deep guides)
└── assets/       # Files used in output (templates, icons, fonts)

• scripts/ — when the agent would otherwise rewrite the same code each run, or when a step needs deterministic reliability. Reference with intent: "Run scripts/validate.py to check the frontmatter." Test scripts by actually running them.
• references/ — move detailed material here to keep SKILL.md lean. Reference each file from SKILL.md and say when to read it. Keep references one level deep.
• assets/ — resources copied or used in the output, not loaded into context.

Do not add README.md, CHANGELOG.md, install guides, or notes about how the skill was made. A skill contains only what the agent needs to do the job.

Workflow

1. Understand the task. Get concrete examples: what should it enable, what phrases should trigger it, what's the expected output? When turning a finished conversation into a skill, mine the steps, tools, and corrections that already happened.
2. Plan resources. For each example, ask what script, reference, or asset would help an agent do it repeatedly. List them before writing.
3. Draft SKILL.md. Write the frontmatter (nail the description), then the body: a one-line summary, the workflow, and concrete examples. Build resources first when they exist.
4. Split for disclosure. If the body grows past ~500 lines or covers multiple variants/domains, keep the core workflow and selection logic in SKILL.md and move the rest into references/ (one file per variant).
5. Validate. Check the frontmatter and naming rules. Then re-read the whole skill for consistency: uniform terminology, heading style, and formatting; and no content repeated across sections or between SKILL.md and references — each fact should live in exactly one place.
6. Iterate on real usage. Use the skill, watch where the agent struggles or wastes steps, and tighten. If every run reinvents the same helper, bundle it as a script. Re-read the draft with fresh eyes and cut.

When editing an existing skill

Read it fully first and preserve its name and folder. Make it shorter and clearer: remove dead weight, replace rigid rules with reasoning, lift the description's triggering, and push detail into references. Match the surrounding house style. Prefer the smallest change that improves it — leave the rest alone.