Skill Authoring

How to write a skill that loads at the right time and does the right thing. Source: Anthropic’s Complete Guide to Building Skills for Claude.

The mental model: progressive disclosure (3 levels)

Frontmatter (YAML) — always in the system prompt. Just enough for Claude to decide when to load the skill. This is the highest-leverage thing you write.
SKILL.md body — loaded only when Claude judges the skill relevant. The full instructions.
Linked files (references/, scripts/, assets/) — loaded on demand. Push detail here to keep the body lean.

Goal: minimal tokens resident, full expertise available when needed.

Folder structure

your-skill-name/        # kebab-case, matches `name`
├── SKILL.md            # required, exact case
├── scripts/            # optional — executable code
├── references/         # optional — docs loaded as needed
└── assets/             # optional — templates, fonts, icons

SKILL.md — exactly that, case-sensitive. No skill.md, SKILL.MD.
No README.md inside the skill folder. Docs go in SKILL.md or references/. (A repo-level README for humans is fine when distributing on GitHub — that lives outside the skill folder.)

The `description` field (get this right first)

Formula: [What it does] + [When to use it / trigger phrases] + [Key capabilities].

Rules:

Must state both what and when (the phrases a user actually says).
< 1024 characters.
No < > angle brackets anywhere in frontmatter — they can inject as tags into the system prompt. Write “followed by a URL”, not <url>. Write “over 1k RPS”, not >1k.
name: kebab-case, no spaces/underscores/capitals, matches the folder. Never contains “claude” or “anthropic” (reserved).
Add explicit trigger phrases and, for broad auto-triggering skills, a negative trigger (“Do NOT use this for…”).

Good vs bad:

✅ Analyzes Figma files and generates dev handoff docs. Use when user uploads .fig files, asks for "design specs", or "design-to-code handoff".
❌ Helps with projects. (vague, no triggers)
❌ Implements the Project entity model with hierarchical relationships. (technical, no user triggers)

Writing the body

Specific and actionable. Run python scripts/validate.py --input {file} — not “validate the data”.
Always include error handling / troubleshooting (a ## Common Issues section with concrete fixes).
Reference bundled files explicitly: “Before X, consult references/api-patterns.md.”
Keep the body focused; move depth to references/.

Testing (3 areas)

Triggering — loads on obvious + paraphrased requests; does NOT load on unrelated topics. Write an explicit should-trigger / should-NOT-trigger list.
Functional — produces correct outputs; scripts succeed; edge cases covered.
Performance — compare with vs without the skill (tokens consumed, tool/API calls, back-and-forth turns).

Controlled comparison (the terum-skills method). When a new skill replaces an old one, or you want to know if a skill earns its place: run the same task three ways (no skill, old skill, new skill), at least 3 fresh claude -p runs each, because one run is noise. Let deterministic checks decide first (tests pass, file exists, output matches). Use an LLM judge only to break a tie, comparing outputs in pairs with the labels hidden. Verdict: PASS if the new skill beats the old one on the checks, NEUTRAL if it ties, FAIL if it loses. Record the cost and time next to the verdict.

Pro tip: iterate on one hard task until it works, then extract the skill. Faster signal than broad testing.

Trigger tuning

Under-triggering (skill doesn’t load when it should; users enable it manually) → add detail and keywords to the description, especially technical terms.
Over-triggering (loads for irrelevant queries; users disable it) → add negative triggers, narrow the description.

Pre-ship checklist + field reference

See references/checklist.md for the full field-requirements table and a copy-paste pre-ship checklist.

Distribution (brief)

Zip the folder → Claude.ai Settings > Capabilities > Skills, or drop in the Claude Code skills directory. For GitHub: public repo, human README at repo root (not in the skill folder), example screenshots. API path needs container.skills + the Code Execution Tool beta. Use the compatibility frontmatter field for platform-specific requirements.