Agent Skills Guide: Learn, Build, Use and Vet Skills
This Agent Skills guide groups every guide we publish by task, from basics to vetting a skill before install. Agent Skills are SKILL.md folders an agent loads only when a task matches.
| Group | What it answers | Guides |
|---|---|---|
| Basics | What skills are and how they load | 3 |
| Build | How to write and test a skill | 1 |
| Use and troubleshoot | How to install a skill and fix triggering | 3 |
| Safety | How to vet a skill before install | 1 |
| Ecosystem | Where skills are listed | — |
| Cost | What a skill costs in tokens | — |
| Do work | Which skills fit a job | 2 hubs |
| Skills vs... | How skills differ from MCP and plugins | 1 |
What are Agent Skills, and how do they work?
Agent Skills are SKILL.md folders that an agent loads only when a task matches. At startup the agent reads just each skill's name and description. They work by loading full instructions on demand and running scripts only when called.
The spec calls this progressive disclosure, in three stages: metadata, instructions, then bundled files. Anthropic released the format as an open standard on 2025-12-18. Six vendors document support today: Anthropic, OpenAI, Google, Microsoft, GitHub and Cursor.
Guides:
- Read what Agent Skills are and what they're used for, our full definition.
- See how Claude picks a skill from its description.
- Study the SKILL.md format, annotated field by field.
How do you build an Agent Skill?
You build an Agent Skill by writing a SKILL.md with a name and a description. The description says when to use it; the body gives step-by-step instructions. Then test that it triggers on the right requests.
The description is the trigger, so its limit matters. The Agent Skills spec allows 1,024 characters. The Claude Help Center sets 200 for claude.ai uploads. The quickstart skill is one file, under 20 lines.
Anthropic's Skill Creator helps you draft and test skills. It scores Conditional 57 with safety grade C. Its trigger evals report 0% recall in issue #1721, still open. Read our Skill Creator verdict before you rely on its numbers.
Guides:
- Follow create an Agent Skill, step by step from folder to first test.
- Check the required SKILL.md fields before you publish.
The mgechev/skills-best-practices repository on GitHub is an outside reference.
How do you install, use and fix Agent Skills?
Install an Agent Skill by placing its folder where your agent looks, such as ~/.claude/skills/. In the Claude app, upload or enable it in Skills settings. To fix a skill that never triggers, check its description against your words.
Claude Code reads ~/.claude/skills/ for personal skills and .claude/skills/ for project skills. The cross-client convention is .agents/skills/, which Codex, VS Code, Cursor and Gemini CLI read. The Claude app needs code execution switched on before skills run.
Guides:
- Learn to install skills in Claude web, desktop and mobile.
- Learn to set up skills in Claude Code at user and project level.
- Learn to fix a skill that won't trigger with a description rewrite.
How do you know an Agent Skill is safe to install?
You know an Agent Skill is safe to install by reading its files and verdict first. Scripts, hooks, network calls and credential requests are the risks. Among the skills we have reviewed, 17 hold safety grade A: no executable code.
Our safety grade comes from reading the skill's files at the reviewed commit. It is not a penetration test.
| Safety grade | Meaning | Skills we have reviewed |
|---|---|---|
| A | No executable code | 17 |
| B | Scripts present, nothing alarming | 12 |
| C | Needs credentials or broad permissions | 10 |
| F | Secrets, undisclosed network endpoints, telemetry or unsafe behaviour | 0 |
Snyk's ToxicSkills study of 2026-02-05 scanned 3,984 skills from ClawHub and skills.sh. It found critical issues in 13.4% of them. Anthropic's platform docs advise using skills only from trusted sources.
Work through the skill vetting checklist before any install.
Where do Agent Skills come from: registries and marketplaces?
Most Agent Skills come from public GitHub repositories, and registries such as skills.sh list and install them. Registries count installs; they do not judge quality. Listings and verdicts differ, so check the verdict before installing.
Vercel launched skills.sh and the skills CLI on 2026-01-20. Other places to find skills are SkillsMP, ClawHub and Awesome lists on GitHub. Popularity and quality split often. Content Research Writer sits in a repository with 76,196 stars and scores Conditional 58. Vercel Labs' own Find Skills earns Recommended with caveats 70 in the Find Skills verdict.
What do Agent Skills cost in tokens?
An idle Agent Skill's cost in tokens is about 100, for its name and description. Its instructions load only when triggered, and the spec recommends under 5,000 tokens.
| Measure | Value | Source |
|---|---|---|
| Idle cost per skill | About 100 tokens | Anthropic platform docs |
| Recommended body size | Under 5,000 tokens | Agent Skills spec |
Claude Code caps its skill listing at 1% of the context window. Size varies widely by skill. Our review of a light skill: Frontend Design estimates about 2,348 tokens per load. The Claude API skill comes to about 25,431 tokens at commit 8a1541c.
What work can Claude do with Agent Skills?
Agent Skills extend the work Claude can do, from design and writing to spreadsheets, slides, video and debugging. Each skill adds a procedure Claude lacks. Our hubs rank the reviewed skills for each kind of work.
Two ranked lists group skills by job: design skills ranked by verdict and writing skills ranked by verdict. Four verdicts show the range of jobs:
- Spreadsheets: the XLSX spreadsheet skill is Recommended with caveats, 70.
- Slides: the PPTX slide skill is Recommended with caveats, 71.
- Video: the Remotion video skill is Recommended, 77.
- Debugging: the Systematic Debugging skill is Recommended, 76.
How do Agent Skills differ from MCP, plugins and prompts?
Agent Skills differ from MCP, plugins and prompts in scope. A skill packages instructions and scripts that load on demand, while an MCP server exposes live tools and data. A plugin installs skills, hooks and MCP servers together.
| Option | What it is | When it loads | Best for |
|---|---|---|---|
| Agent Skill | Instructions plus optional scripts | On a description match | A repeatable procedure |
| MCP server | Live tools and data | When the agent calls a tool | External systems |
| Plugin | Skills, subagents, hooks and MCP servers as one unit | At install | Shipping a full setup |
| Subagent | A separate worker with its own context | When delegated | Parallel or isolated tasks |
| Prompt or CLAUDE.md file | Plain instructions | Once, or every session | Rules that always apply |
Sources: the Agent Skills spec, the Claude Help Center, and the Claude Code plugins docs. Agents and subagents use skills; they do not replace them.
Read when to use a skill instead of MCP for the full comparison.
You know how skills work. Next: which ones are worth installing.
Which Agent Skills pass our verdicts?
Of the Agent Skills we have reviewed, 10 earn Recommended, 10 Recommended with caveats and 18 Conditional. Our ranking opens with Designer Skills Collection, Remotion Best Practices, Animate, Emil Design Engineering and Frontend Design.
One skill is Not Recommended. The table below shows the top five, ordered by score.
| # | Skill | Verdict | Score | Safety grade | Confidence |
|---|---|---|---|---|---|
| 1 | Designer Skills Collection | Recommended | 78 | B | Moderate |
| 2 | Remotion Best Practices | Recommended | 77 | B | Moderate |
| 3 | Animate | Recommended | 77 | A | Low |
| 4 | Emil Design Engineering | Recommended | 76 | A | Moderate |
| 5 | Anthropic's Frontend Design verdict | Recommended | 76 | A | Moderate |
Go further with the best Agent Skills, ranked by verdict, or browse every reviewed skill. The methodology page explains how a verdict is reached.
What changed in Agent Skills recently?
Agent Skills changed fast in 2026, and six vendors now document support for the format. Recently, Claude Code added a /design skill and a /skill-doctor command. Snyk found critical issues in 13.4% of 3,984 registry skills.
- 2025-12-18: Anthropic publishes Agent Skills as an open standard.
- 2026-01-20: Vercel launches skills.sh and the
skillsCLI. - 2026-02-05: Snyk publishes ToxicSkills, its scan of 3,984 registry skills.
- 2026-08-17 to 21: Claude Code ships the
/designskill as a research preview, v2.1.234+. - Week 36 of 2026: Claude Code adds
/skill-doctor, which shows each skill's context cost. - 2026-10-14 and 2026-10-15: VS Code and Microsoft Agent Framework update their skills docs.
The Help Center notes that Claude Code v2.1.273+ syncs skills from a claude.ai account.
Common questions
Where do beginners start with Agent Skills?
Beginners start with our definition of Agent Skills, then the SKILL.md format. After that, pick the Claude Code or Claude app setup guide.
Are Claude skills the same as Agent Skills?
Yes. Claude skills use the Agent Skills format, and Claude adds features such as invocation control on top.
Do I need to code to make a skill?
No. A skill can be one SKILL.md file of plain instructions, and scripts are optional.
How do I check a skill before installing it?
Read its verdict's safety grade and listed failures first. The vetting checklist covers the rest.
Do Agent Skills work outside Claude?
Yes. Six vendors document support, and the agentskills.io client list names 46 agent products.
Is there an Agent Skills guide PDF?
Yes. Anthropic publishes "The Complete Guide to Building Skills for Claude" as a free PDF.