1. What is a skill?
An AI agent skill is a folder of instructions (and optionally scripts and reference files) that an agent loads when a task matches the skill's description. Think of it as an onboarding guide for a new hire: you don't retrain the model, you hand it a written procedure for one kind of job.
Without a skill
You paste the same 40-line instructions into every chat, or the agent guesses your preferences every time.
With a skill
The agent sees a one-line description, recognizes when it applies, and loads the full procedure on its own.
Portable
The format is an open standard (agentskills.io), so the same folder can work in Claude Code, other coding agents, and more.
Sources: Anthropic engineering post, Agent Skills specification.
2. Anatomy of a skill
This is progressive disclosure: the agent pays a small token cost for every skill (metadata), a bigger cost only for the skill it actually uses (body), and loads extra files only when a step needs them.
my-skill/ ├── SKILL.md # Required: frontmatter + instructions ├── scripts/ # Optional: code the agent can run ├── references/ # Optional: long docs loaded only when needed └── assets/ # Optional: templates, sample files
The frontmatter (the only required part)
--- name: weekly-kpi-report description: Builds the weekly KPI dashboard summary from the sales CSV. Use when the user asks for a weekly report, KPI summary, or dashboard update. --- # Weekly KPI report 1. Read the CSV in data/ ...
| Field | Required | Rule |
|---|---|---|
name | Yes | 1–64 chars, lowercase letters, digits, hyphens. No leading/trailing or double hyphens. Must match the folder name. |
description | Yes | 1–1024 chars. Say what it does AND when to use it, with keywords the user would say. |
license, compatibility, metadata | No | Extra info for other people and tools. |
allowed-tools | No | Experimental. Pre-approved tools for the skill. |
Source: agentskills.io/specification
3. How people use skills
IndividualPersonal workflow
Writing style, code review checklist, your company's report format. Stored in ~/.claude/skills/ or similar.
TeamShared in a repo
Committed to .claude/skills/ so every teammate gets the same deploy or test procedure.
CommunityInstalled from a hub
Browse skills.sh or GitHub, install a skill like a package. Popular examples: writing-plans, systematic-debugging, test-driven-development.
Rough mix of skill categories (illustrative, not measured)
The bar lengths are a rough illustration of the category mix, not measured data. Use them as a sense of the landscape.
4. Write your first skill (step by step)
Pick one repeatable task
Good: "turn meeting notes into action items". Too broad: "help me with work". A skill should be something you do again and again.
Do the task once with the agent, then write down what you corrected
Your corrections are the most valuable part. They are the rules your skill needs.
Write the SKILL.md
Keep the body short. Claude is already smart; only add what it does not know: your format, your tools, your rules.
Test with 3 real prompts
Anthropic's guide recommends at least three evaluations. Test with the models you actually use.
Iterate from failures
When the agent misses, add the missing rule. When it over-applies, narrow the description.
Example: a small, good skill
---
name: meeting-action-items
description: Turns meeting notes into a table of decisions, owners and due dates. Use when the user pastes meeting notes or asks for action items, follow-ups or a recap.
---
# Meeting action items
1. List decisions first, one per line, in past tense.
2. For each action: owner (name, or "UNASSIGNED"), task (verb first), due date (or "NONE").
3. If a date is relative ("next Friday"), convert it using today's date and state the exact date.
4. End with a list of open questions. Do not invent owners or dates.
## Output format
| # | Owner | Task | Due |
|---|-------|------|-----|
Why it works: the description contains the words the user will say ("meeting notes", "action items"), the steps are specific, and it forbids the one mistake people hate (invented owners).
Good vs. weak description
description: Helps with meetings.
The agent cannot tell when to load it.
description: Turns meeting notes into action items with owners and due dates. Use when the user pastes notes or asks for a recap.
Says what, when, and which keywords trigger it.
5. How to grow a skill over time
Most good skills are not written in one go. They evolve through a loop:
Design principles to check against
- Concise: every paragraph should justify its token cost.
- Match freedom to risk: text guidance for judgment calls; exact scripts for fragile steps (e.g. database migrations).
- One level of references: SKILL.md links to files; those files should not link further.
- Keep SKILL.md under ~500 lines.
- Avoid time-sensitive facts in the body; put old patterns in a clearly marked section.
Sources: Skill authoring best practices, Agent Skills specification.
6. Skills in automated workflows
A skill tells the agent how to do a task. Automation decides when it runs and what happens around it. Claude Code's docs and Anthropic's guide describe several layers that work together:
/deploy. Holds the procedure.Example pipeline: weekly KPI report
Automation patterns people use
| Pattern | What it looks like | Role of the skill |
|---|---|---|
| Plan → execute → verify | writing-plans, then executing-plans, then a verification pass | Each step is a skill with a checklist |
| Parallel fan-out | Several subagents each handle one part of a task | Defines the job each subagent does |
| Scheduled digest | Cron searches sources and writes a summary to a page | Holds the format, sources and rules for the digest |
| Event-driven check | A hook runs a linter after every file edit | The hook is deterministic; the skill explains how to fix the errors |
| Autonomous loop | Agent works through a task list, commits passing work, retries failures | Each item follows the same skill; verification gates completion |
Rule of thumb
Use a skill for procedures you want the model to follow with judgment. Use a hook for things that must always happen. Use a subagent for work that should not flood your main context. Put a schedule around the skill when it should run without you.
Sources: Claude Code: extend features overview, Claude Code hooks guide, Steering Claude Code: skills, hooks, rules, subagents, skills.sh: agent workflow skills.
7. Compare tool: check your SKILL.md against the spec
Want to take a skill apart and rebuild it? Open the Skill Canvas: it breaks a SKILL.md into cards you can drag, edit and export as a new skill.
Paste two SKILL.md files, or load one from a GitHub URL. The tool checks the rules from the spec, then compares size, structure and description quality. Everything runs in your browser; nothing is uploaded.
Skill A
Skill B
8. Case study: a design skill taken apart
frontend-design is Anthropic's public skill for building interfaces that do not look templated. It is a useful one to study because it has no scripts and no reference files: everything it does, it does with words. Open it in the Skill Canvas →
Size71 lines, about 1,500 words
Roughly 2,350 tokens, about half of the 5,000 recommended for a body. One file plus a license.
ShapeA brief, not a checklist
Five sections of prose. The only numbered list is a catalogue of looks to avoid, not a procedure.
FreedomHigh, on purpose
Design is a judgment call, so the skill gives reasons and priorities and leaves the choices to the agent (see "match freedom to risk" in section 5).
Where the words go (measured)
Word counts per section of the file as of November 2026. Six in ten words sit in two sections: the principles and the process.
What each section does
| Section in the file | Canvas card type | Job |
|---|---|---|
| Title and opening paragraph | Title & overview | Sets a role (design lead at a studio) and the stakes: the client has already rejected templated work. |
| Ground your designs in the subject matter | Notes | Before designing, name the subject, the audience and the page's main job. Distinctive choices come from the subject's own world. |
| Design principles | Rules | Positions on the hero, typography, structure, motion and copy. Each names the default treatment and says when it is justified. |
| Process: plan, review, build, critique | Steps | Lists five looks that generated designs cluster around, then sets a two-pass method: write a token plan, test it against the brief, only then write code. |
| Restraint and self-critique | Notes | Be bold in one place only. Sets a quality floor (responsive, keyboard focus, reduced motion) and asks for screenshot reviews. |
| More on writing in design | Notes | Interface copy rules: name things the user's way, buttons say what happens, errors explain the fix. |
Card types are what the Skill Canvas assigns from each heading. Three of five land in "Notes" because the headings describe ideas, not the usual Steps / Rules / Output slots.
Techniques worth copying
What this site's checks say
- The description says what the skill does but has no "Use when …" clause. At 29 words it is still specific enough to trigger on UI work.
- No examples section (a Skill Canvas tip). The skill describes looks in words and never shows one.
Compare tool score: 88 / 100. The Canvas does not flag missing steps, because it counts the numbered catalogue of looks as steps. The real method is written as paragraphs.
- Name format, description length (204 of 1,024 characters) and body length (well under 500 lines).
- No vague filler phrases. Even the taste guidance is concrete enough to test.
Paste it into the Compare tool above to see the score next to your own skill.
What to take from it
For judgment-heavy work, write the skill as a brief: a role, the failure you want to avoid described in detail, a checkpoint before the costly step, and a rule for who wins when instructions conflict. Save numbered steps and scripts for tasks where one wrong move breaks things.
Source: anthropics/skills: frontend-design (Apache 2.0). The analysis is this site's own reading of the file.
9. Videos and articles to learn from
Official docs and articles
- Equipping agents for the real world with Agent Skills (Anthropic, Oct 2025). Why skills exist and the three levels of detail.
- Agent Skills specification. The exact format rules. Read this before writing.
- Skill authoring best practices. Concise writing, freedom levels, and a checklist.
- Extend Claude with skills (Claude Code docs). Creating and invoking skills.
- Automate actions with hooks (Claude Code docs). Deterministic automation.
- Steering Claude Code. A decision table: when to use CLAUDE.md, skills, hooks, subagents.
- Skills vs. other Claude Code features (Anthropic Academy). Short course.
- skills.sh: agent workflow skills. Real, installable skills for planning, debugging and parallel agents.
- skill-creator (Anthropic). A real skill that helps you write skills. Read it as an example.
- Report: Progressive Disclosure of Agent Skills (arXiv). Research on the cost and latency of lazy-loading skills.
Videos
- Claude Code Skills - The Only Tutorial You Need (Leon van Zyl, 21 min). Start here for a walkthrough.
- Agent Skills in AI Agents - Complete Tutorial (ErrorFixer, 7 min). SKILL.md anatomy and progressive disclosure.
- I Built Custom Agent Skills from Scratch. Building a skill step by step (OpenCode, but the format is the same).
- Claude Code Skills & skills.sh - Crash Course. Installing skills and the open standard.
- Building Agent Skills with GitHub Copilot in VS Code (TechyTacos, 9 min). Creating a skill in another tool.
Video titles and channels are as listed on YouTube at the time of research. Check the length and date before watching.