skill-authoring

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)

1. 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.
2. SKILL.md body — loaded only when Claude judges the skill relevant. The full instructions.
3. 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)