Claude Skills Explained: The 2026 Guide to Agent Skills, SKILL.md, and MCP

Anthropic opened the Agent Skills standard in Q1 2026, and within three months the GitHub trending page was wallpapered with skills repos. Karpathy's CLAUDE.md skills pack passed 62,000 stars. Addy Osmani's production skills collection hit 18,000. Vercel launched skills.sh as the open directory and find-skills alone crossed half a million installs.

The problem: almost nobody can cleanly explain what a Skill is, how it differs from MCP, or when you should reach for one over a plain tool call. This guide fixes that — with a minimal working SKILL.md, a comparison table that separates Skills from MCP, Tools, and Subagents, and a decision framework you can actually apply.

Standard, features, and ecosystem verified as of May 2026.

A Claude Skill is a folder with a SKILL.md file (YAML frontmatter + Markdown) that teaches the agent a repeatable procedure — its frontmatter says when to use it, its body says how.

📋 What You'll Need

• Claude Code installed locally (or Claude Pro/Max/Team/Enterprise for the hosted version)
• A terminal and a text editor
• Familiarity with YAML frontmatter (the same syntax used in Jekyll, Hugo, or your CLAUDE.md)
• Optional: a GitHub account if you want to publish to skills.sh later

If you're brand new to the surrounding tooling, start with the Claude Code Workflow Guide and come back. Everything below assumes you can drop a file into .claude/ and run a slash command.

🧩 What a Claude Skill Actually Is

Strip the marketing and a Claude Skill is a folder that contains:

1. A required SKILL.md file (YAML frontmatter + Markdown instructions)
2. Optional supporting files: scripts, templates, reference docs, examples

The frontmatter tells Claude when to use the skill. The Markdown tells Claude how to do the task. That's the entire primitive.

my-skill/
├── SKILL.md           # Required: instructions + frontmatter
├── reference.md       # Optional: loaded only if needed
├── examples/
│   └── sample.md      # Optional: example outputs
└── scripts/
    └── helper.py      # Optional: Claude can execute

Where you drop the folder controls who can use it:

Higher-priority locations win on name conflicts: enterprise > personal > project. Plugin skills get their own plugin:skill-name namespace so they can never clash.

📄 What Is a SKILL.md File?

A SKILL.md file is the one required file in every skill — plain Markdown with two parts. The YAML frontmatter at the top (only description is required) tells Claude when to reach for the skill; the Markdown body below it tells Claude how to do the task. No JSON, no schema, no build step.

Crucially, SKILL.md is now an open standard (published at agentskills.io), so the same file works unchanged across Claude Code, Cursor, Windsurf, Codex, and Gemini CLI. Write it once; run it in any agent that speaks the format.

✍️ Your First Skill: A Minimal SKILL.md

Here's a working skill that teaches Claude to explain code with analogies and ASCII diagrams. Drop it in ~/.claude/skills/explain-code/SKILL.md:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when the user asks how something works, is onboarding to a new codebase, or says "walk me through this".
---

When explaining code, always include:

1. **Start with an analogy** comparing the code to something from everyday life.
2. **Draw an ASCII diagram** of the flow, structure, or relationships.
3. **Walk through step-by-step** what actually happens at runtime.
4. **Highlight one gotcha** — a common mistake or misconception.

Keep it conversational. For complex concepts, use more than one analogy.

You now have two ways to invoke it:

• Direct: type /explain-code src/auth/login.ts in Claude Code
• Automatic: Claude loads it when you ask a matching question like "how does this work?"

That's the whole loop. No SDK, no config file, no build step. One Markdown file and you've extended Claude.

Frontmatter fields you'll actually use

Only description is recommended. Everything else is optional but earns its keep in specific cases:

🔍 How Progressive Disclosure Works (Why Skills Stay Cheap)

The thing that makes Skills scale is progressive disclosure. In a normal Claude Code session, only the descriptions of your skills sit in context. The full SKILL.md body only loads when the skill is actually invoked — either by you typing /name or by Claude deciding the description matches your request.

This is why you can have 50 skills installed without drowning the context window. A 40-line description index costs almost nothing. A 500-line procedure only enters context when you need it.

┌─────────────────────────────────────────────────────┐
│  Session context                                     │
│  ─────────────────────────────────────────────────  │
│  • CLAUDE.md                      (always loaded)    │
│  • skill descriptions (1,536 chars each, capped)     │
│  • conversation                                      │
│  • [full skill body]  ◄── loads only when invoked    │
└─────────────────────────────────────────────────────┘

Two knobs change this behavior:

• disable-model-invocation: true removes the skill's description from context entirely. You can still run /name manually, but Claude won't auto-pick it.
• Subagents with preloaded skills inject the full skill body at startup instead of deferring — useful for specialized agents.

⚡ Skills 2.0: Hooks, Subagents, Shell Injection, Tool Restrictions

The April 2026 updates collectively called "Skills 2.0" turned Skills from a nicer prompt wrapper into a legitimate programming primitive. Four features matter most.

1. Subagent forking with context: fork

Add context: fork and your skill runs in an isolated subagent with its own context window. The skill body becomes the subagent's prompt. Useful for research tasks that would otherwise pollute your main conversation.

---
name: deep-research
description: Research a topic thoroughly without cluttering the main conversation.
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep.
2. Read and analyze the code.
3. Summarize findings with specific file references.

Running /deep-research authentication flow spins up a fresh Explore agent, runs the task in isolation, and returns a summary to your main session. Your context stays clean.

2. Shell injection with !`command`

You can run shell commands before Claude sees the skill content. Output replaces the placeholder, so Claude receives real data rather than an instruction to go fetch it.

---
name: pr-summary
description: Summarize the current pull request.
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request in three bullets...

The three !`gh ...` commands execute first. Claude never sees the command — it sees the output. This is preprocessing, not tool use.

3. Tool restrictions with allowed-tools

allowed-tools pre-approves specific tools so Claude doesn't stop to ask permission each time the skill runs. Combined with disable-model-invocation: true, this is how you build safe-ish automation primitives.

---
name: commit
description: Stage and commit current changes.
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

Stage and commit:
1. `git status` to see what changed.
2. Group related changes.
3. Write a commit message following our style.
4. Commit and confirm.

4. Lifecycle hooks with hooks

Skills can hook into session events to enforce behavior deterministically rather than hoping the model complies. This is how teams are wiring skills to always run linters, validate specs, or block risky tool calls.

---
name: api-conventions
description: Enforce this codebase's API design rules.
hooks:
  PreToolUse:
    - command: "./scripts/validate-endpoint.sh"
---

When writing API endpoints:
- Use RESTful naming.
- Return consistent error formats.
- Include request validation.

🆚 Skills vs MCP vs Tools vs Subagents: The Comparison

This is the table most developers wish existed. All four primitives are Anthropic-native, they look superficially similar, and picking the wrong one wastes hours.

The sentence that makes this click: MCP hands Claude a hammer. A Skill explains how to use the hammer to drive nails. If you find yourself writing a Skill that needs to fetch real data, you pair it with an MCP server. They're complementary, not competing.

For a deeper MCP primer, see the MCP Servers Explained guide, and if you want to build your own MCP, the Build a Custom MCP Server tutorial walks through Python and TypeScript implementations end-to-end.

🏪 Where to Find Skills: The Marketplace Landscape

Three ecosystems matter as of April 2026. Most people use all three without realizing they're separate.

1. Anthropic's official skills

Ship inside Claude Code and the claude.com app. Currently includes:

• Document generation: Excel (.xlsx), PowerPoint (.pptx), Word (.docx), fillable PDFs
• Bundled Claude Code skills: /simplify, /batch, /debug, /loop, /claude-api, /init, /review, /security-review
• Custom Skills API for Team and Enterprise

These are available to Pro, Max, Team, and Enterprise plans. No install step — they're already on your system.

2. Community repositories

addyosmani/agent-skills is the one most teams converge on — each skill has an anti-rationalization table, red flags, verification steps, and a progressive-disclosure layout. Latest release is 0.5.0 (April 10, 2026), MIT licensed.

3. Vercel's skills.sh directory

Launched January 20, 2026 as the open directory and leaderboard for agent skill packages. Works across 19 agents — not just Claude Code, but also Cursor, Codex, Copilot, Windsurf, Gemini CLI, and others.

npx skills add vercel-labs/agent-skills

The leaderboard is public and updated in real time based on install telemetry. As of March 2026, find-skills crossed 579,000 installs and vercel-react-best-practices passed 216,000.

🧭 A Decision Framework: Skill, MCP, or Tool Call?

Use this order every time. It's a five-second check that saves you an hour.

1. Does Claude already have a built-in tool for this? (Read, Bash, WebFetch, Grep, Edit.) If yes — just call it. Don't wrap it in anything.
2. Do you need to connect to an external system (GitHub, a DB, your CRM, a browser)? You need an MCP server. Install one, or write one.
3. Are you repeating the same procedure more than twice? Write a Skill. The threshold really is twice — below that, just type it out.
4. Does the procedure need live external data? Pair a Skill with an MCP connector. The Skill is the playbook, the MCP is the data source.
5. Does the task need its own context window (long research, parallel work, isolation from the main conversation)? Use a Subagent — either via context: fork in a skill or a dedicated .claude/agents/ file.

Three common wrong turns:

• Writing a Skill when you needed an MCP. A Skill can't fetch your GitHub issues on its own. If your instructions read "first, go look up X in Y system," you need an MCP.
• Writing an MCP when you needed a Skill. If your instructions are purely procedural ("always run tests before committing, always write the message like this"), that's a Skill.
• Putting the whole playbook in CLAUDE.md. CLAUDE.md stays in context every turn. A 400-line procedure there costs you tokens on every single message. Move it to a Skill and recover the context.

For more on the CLAUDE.md side, the CLAUDE.md Project Instructions Standard guide covers what belongs there versus in a Skill.

🛠️ Troubleshooting

💰 Cost and Availability

Skills themselves cost nothing — they're just Markdown files. The cost is token usage during invocation, which is almost always cheaper than stuffing the same content into CLAUDE.md.

The Agent Skills standard itself is open — Anthropic published the spec at agentskills.io and tools from Cursor to Vercel to Microsoft's .NET team now consume the same SKILL.md format. Skills you write for Claude will increasingly work unchanged in other agents.

Frequently Asked Questions

What is a Claude Skill?

A Claude Skill is a folder containing a SKILL.md file (YAML frontmatter + Markdown instructions) and optional scripts, templates, and examples. The frontmatter tells Claude when to use it; the Markdown tells it how. It teaches the agent a repeatable procedure.

Claude Skills vs MCP — what's the difference?

A Skill is a Markdown procedure ("how to do X"); MCP is an external service that provides data and actions ("read/write X"). MCP hands Claude a hammer; a Skill explains how to drive nails with it. If your skill needs live external data, pair it with an MCP server.

How does a Skill stay cheap on tokens?

Progressive disclosure — only the ~1,536-char description sits in context. The full SKILL.md body loads only when the skill is invoked (by /name or auto-match), so you can have 50 skills installed without bloating the context window.

When should I write a Skill vs use CLAUDE.md or a tool?

Use a built-in tool if one exists; an MCP server to connect to external systems; a Skill when you repeat a procedure more than twice; and a subagent (context: fork) when a task needs its own context window. Keep facts in CLAUDE.md, procedures in Skills.

Where do I find ready-made Claude Skills?

Browse Vercel's skills.sh directory (works across 19 agents) and community repos like addyosmani/agent-skills and forrestchang/andrej-karpathy-skills before writing your own — common ones (commit style, PR review, write a spec) are already solved.

🚀 What's Next

• 🧠 Convert three of your CLAUDE.md procedures into Skills. You'll recover context budget immediately. Good candidates: commit style, PR template, deployment steps.
• 🔌 Pair your next Skill with an MCP server. Pick one fetchable data source (GitHub issues, Postgres, your analytics) and wire them together.
• 📦 Install addyosmani/agent-skills as a starting library. Faster than writing from scratch, and the patterns are worth studying.
• 🧪 Use context: fork for your next research task. The context-isolation win is underrated until you try it.
• 🏷️ Browse skills.sh before writing anything. Your problem is probably solved.
• 📚 Read the Cursor IDE Tips and Tricks guide. Cursor skills consume the same standard — most patterns transfer directly.

For the rest of the Claude Code stack, see the Claude Code Workflow Guide and the MCP Servers Explained primer — Skills, MCP, and CLAUDE.md work best when you understand all three as one system.