Agent Skills + Anthropic's guide

Pasting the same checklist into every chat? A skill teaches Claude once — and Anthropic has published an official 33-page guide on how to build one properly. 🧩

What it does

A skill is a folder with a SKILL.md file (instructions plus optional scripts, reference docs and templates) that extends the agent with a specialized capability. The model picks the skill up on its own when the task matches its description — no copy-pasting the same checklist into every chat.

The key difference from a prompt is progressive disclosure (context loaded in stages), across three levels:

• Level 1 — the YAML frontmatter (name + description): always in the system prompt — just a couple of lines of metadata per skill. That's why you can keep dozens of skills without burning context.
• Level 2 — the body of SKILL.md: loaded only when the skill fires on a task.
• Level 3 — nested files (references/, scripts/, assets/): read/executed as needed; script code never enters the context — only its output does.

That's also what separates a skill from a Prompt (just text) and from MCP (a connector server): MCP grants access to tools ("what Claude can do"), a skill supplies the knowledge of how to use them properly ("how it should be done").

How to set it up

A minimal skill is frontmatter plus markdown instructions in a single SKILL.md:

---
name: my-skill
description: What it does and WHEN to use it. Put the key situation (the trigger) first.
---

## Instructions
Step-by-step directions for the model to follow…

Where it goes depends on the platform:

• Claude Code — ~/.claude/skills/<name>/SKILL.md (personal) or .claude/skills/<name>/SKILL.md (project-level, in git).
• claude.ai (Pro/Max/Team/Enterprise) — upload the skill as a zip archive in settings.
• Claude API — upload via /v1/skills, then reference the skill_id in the container parameter.

What Anthropic's official guide (33 pp.) recommends

Anthropic published a free guide, "The Complete Guide to Building Skills for Claude" — 6 chapters: Fundamentals, Planning & Design, Testing & Iteration, Distribution, Patterns & Troubleshooting, Resources. (IG teardowns call it "32 pages" — the original PDF has 33.) The practices, straight from the source:

• Start with use cases, not code. Describe 2–3 concrete scenarios. Anthropic calls out three typical categories: producing documents/assets, automating workflows, strengthening an MCP integration.
• The description decides everything. The description must state BOTH "what it does" AND "when to use it" — with the real trigger phrases you actually say. Up to 1024 characters. This is the first level of progressive disclosure, always in the system prompt.
• Iterate on one hard task. Get Claude to succeed on a single case → extract the winning approach into a skill. That's faster than running a broad test set right away.
• Measure the benefit honestly (A/B). Anthropic's benchmarks: firing on ~90% of relevant requests; fewer tool calls and tokens than without the skill; zero failed calls per run.
• Respect the structure rules. The file must be exactly SKILL.md (case matters), the folder in kebab-case, no README.md inside. The words "claude"/"anthropic" in the name and XML brackets < > in the frontmatter are banned — the frontmatter goes into the system prompt, so this is injection protection.
• Speed. A working skill really can be built in one sitting — about 15–30 minutes via skill-creator.

When to pick it

• You paste the same checklist/procedure into a chat over and over.
• A section of CLAUDE.md has grown into a procedure rather than a fact — move it into a skill (it loads only when invoked).
• You need a capability with scripts (deterministic operations), not just text.

Example

Drop the summarize-changes/ folder into ~/.claude/skills/ → ask "what did I change?" — the model picks the skill up from its description, or you call /summarize-changes directly. The key rule from the guide: the description has to contain the words you actually say, otherwise auto-triggering won't fire.