Claude Skills explained: SKILL.md, and how a skill differs from CLAUDE.md, hooks and MCP

Say you keep pasting the same checklist into Claude Code. Review this pull request, then check the tests, then write the summary in this exact shape. You paste it on Monday, again on Tuesday, and by Friday you wonder why you are the one keeping the memory.

A skill is Anthropic's answer to that. I am Neon, and I like tools that stay out of the way until needed. Skills do exactly that, which is why they are worth ten minutes of your time.

This page reads Anthropic's documentation and the open Agent Skills spec. It is not a tutorial I ran. New to the tool itself? Start with Claude Code for vibe coders. For how the major builders compare, see Lovable vs Cursor vs Claude Code.

What is a Claude Skill?

A skill is a folder that contains a file named SKILL.md. The file has a short header with a name and a description, then plain Markdown instructions. Claude reads the instructions when your request matches the description. Anthropic's docs put it this way: you create a SKILL.md file with instructions and Claude adds it to its toolkit.

The open spec describes the folder like this, and the folder can hold more than the one file:

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

The pitch from the Agent Skills site is packaging "procedural knowledge and company-, team-, and user-specific context into portable, version-controlled folders that agents load on demand." In plain words: a skill is a how-to you write once and Claude pulls out when the job comes up.

You can also start one yourself. Typing /skill-name at the Claude Code prompt runs it directly, and Claude can load it on its own when the description fits.

What goes inside SKILL.md?

The file starts with YAML frontmatter between two --- lines. Two fields are required in the open spec: name and description. Everything after the frontmatter is the instructions, in any Markdown you like. The spec sets no format rules for the body and suggests step-by-step instructions, examples and edge cases.

The limits that matter, from the spec:

• name: 1 to 64 characters. Lowercase letters, numbers and hyphens. It cannot start or end with a hyphen, cannot contain --, and must match the folder name.
• description: 1 to 1,024 characters. It should say what the skill does and when to use it.
• Optional: license, compatibility (up to 500 characters), metadata and allowed-tools, which the spec marks experimental.

The description is the most important line you write. Claude matches your request against it, so Anthropic's docs and the spec both say it must cover what the skill does and when to use it. The spec's own contrast: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents..." is good, and "Helps with PDFs." is poor.

Claude Code adds its own fields on top of the open spec. The docs list, among others, when_to_use, argument-hint, disable-model-invocation, user-invocable, context, paths, hooks, model and effort. Claude Code truncates description and when_to_use together at 1,536 characters. Both the spec and Claude Code say to keep SKILL.md under 500 lines and move detail into separate files.

Our illustration: a small skill

This one is ours, written from the documented fields. We have not run it. It is a pull-request review checklist, the kind of procedure the docs say belongs in a skill, not in a prompt.

---
name: review-pr
description: Reviews a pull request against our team checklist and writes a short summary. Use when the user asks for a PR review or pastes a PR link.
disable-model-invocation: true
---

# Review a pull request

1. Read the diff and list every file changed.
2. Check each change against the checklist in checklist.md.
3. Flag anything that touches auth, payments or database migrations.
4. Write a summary: what changed, what worries you, what to test.

Two details. disable-model-invocation: true is a Claude Code field. Per the docs it stops Claude from loading the skill automatically, so it runs only when you type /review-pr. The line checklist.md points at a second file in the same folder, which is the next section's whole point.

How does a skill load? (progressive disclosure)

A skill loads in three stages. At startup Claude gets only each skill's name and description, about 100 tokens per skill. When your request matches, it reads the SKILL.md body, under 5,000 tokens recommended. Scripts, references and assets stay on disk until the instructions point at them.

The docs call this progressive disclosure. The practical upshot, in Anthropic's words: "you can install many Skills without context penalty: until a Skill is triggered, only its name and description occupy context." If you had 50 skills, the always-on cost would be roughly 5,000 tokens, by our arithmetic on the 100-token figure.

Scripts are the quiet win. Anthropic's overview says that when Claude runs a bundled script, "the script's code never enters context," and only the output does. So a skill can ship a validator or a converter without paying for its source on every run.

Three more behaviors from the Claude Code docs:

• Many skills, tight budget. If you have a lot of them, Claude Code drops some descriptions to fit the listing's character budget, which scales at 1% of the model's context window. Names always stay. Dropped descriptions remove the keywords Claude needs to match.
• Once loaded, it stays. The rendered SKILL.md enters the conversation as one message and stays across later turns. Every line is a recurring token cost, which is why the docs say to state what to do and skip the narration.
• Compaction keeps it. When a long session is summarized, Claude Code re-attaches the most recent use of each skill, keeping the first 5,000 tokens of each. Re-attached skills share a 25,000-token budget.

Where do skills live?

In Claude Code, a skill lives in a folder in one of a few places. Personal skills go in ~/.claude/skills/<skill-name>/SKILL.md and follow you across projects. Project skills go in .claude/skills/ inside the repo. Plugins can bundle skills, and enterprise admins can deploy them. Claude Code picks up edits mid-session.

Anthropic's table, shortened:

When the same name exists twice, the docs rank enterprise over personal and personal over project. Claude Code watches these folders and picks up changes within the current session. A brand-new top-level skills folder needs /reload-skills.

One trap sits outside Claude Code. Anthropic's overview says custom skills do not sync across surfaces. A skill uploaded to claude.ai is not on the API, one uploaded to the API is not on claude.ai, and Claude Code skills are filesystem-based and separate from both. On claude.ai custom skills are individual to each user. On the API they are shared across the workspace.

Skill vs CLAUDE.md, slash commands, hooks and MCP

Pick by job. CLAUDE.md holds facts Claude should always know. A skill holds a procedure Claude needs sometimes. A slash command is now just a skill you start by name. A hook runs code at set moments and can block an action. An MCP server connects Claude to outside tools and data.

Skill vs CLAUDE.md

CLAUDE.md is loaded into every session. A skill body is not. The docs' rule of thumb is to create a skill "when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact." The memory docs add that each session starts with a fresh context window, and CLAUDE.md is how knowledge carries over. Facts go there. Long procedures go in a skill. For the thinking behind what to put in context at all, see context engineering for vibe coders.

Skill vs slash command

They merged. The docs say custom commands "have been merged into skills." A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way, and old command files keep working. A skill adds a folder for supporting files, frontmatter that controls whether you or Claude invokes it, and automatic loading when relevant.

Skill vs hook

A hook runs code. A skill supplies instructions. The memory docs are blunt that Claude treats CLAUDE.md as "context, not enforced configuration," and that to block an action regardless of what Claude decides you use a PreToolUse hook. A skill is the same kind of thing as CLAUDE.md here: Claude follows it, but nothing forces it to. The two can combine, because a skill's frontmatter can include a hooks block that Claude Code registers when the skill is invoked and keeps for the rest of the session. Details on hooks are in Anthropic's docs. We cover the events and exit codes in a separate hooks guide when it publishes.

Skill vs MCP

MCP connects Claude to things. Anthropic's MCP page says Claude Code can connect to hundreds of external tools and data sources through the Model Context Protocol, "an open source standard for AI-tool integrations," and that servers give access to your tools, databases and APIs. A skill does not connect to anything by itself. It tells Claude how to do a job, and it can mention an MCP tool the job needs. The MCP page does not compare itself to skills, so that framing is mine, not Anthropic's.

Skill vs subagent

A skill can run in a forked subagent. Set context: fork and the docs say you write the task in the skill and pick an agent type to run it. A forked skill using the built-in Explore agent sees only the SKILL.md content and that agent's own system prompt, not CLAUDE.md or git status.

Is the Agent Skills format open?

Yes. The Agent Skills site says the format was "originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products." The GitHub repository at agentskills/agentskills lists code under Apache 2.0 and documentation under CC-BY-4.0, and shows about 25,900 stars when I read it.

The site's client showcase lists tools that read the same SKILL.md format. Names on it include Claude Code, Claude, Cursor, GitHub Copilot, VS Code, Gemini CLI, OpenAI's Codex, OpenCode, Goose and Kiro. Support details differ by product, and the spec itself says allowed-tools support "may vary between agent implementations." So a skill you write for one agent is a good start in another, not a guarantee.

The spec ships a validator too. The repo's skills-ref library checks that a skill's frontmatter and naming follow the rules, with a skills-ref validate ./my-skill command.

Are skills safe to install?

Treat a skill like software you install. Anthropic's overview says to use skills only from trusted sources, meaning ones you wrote or got from Anthropic. A skill can carry instructions and code, so a malicious one can steer Claude to use tools in ways that do not match its stated purpose. The docs name data exfiltration and unauthorized system access as possible risks.

Anthropic's audit advice is concrete:

• Read every file in the skill, not just SKILL.md. That includes scripts and images.
• Look for unexpected network calls or file access that do not match the stated purpose.
• Be wary of skills that fetch data from external URLs, since fetched content can carry instructions and dependencies can change later.
• Be extra careful before putting a skill into a system with sensitive data.

On the API, skills run in a sandbox with no network access. In Claude Code, the overview says skills "have the same network access as any other program on the user's computer." That is a very different risk profile, so read before you copy a skill from a stranger's repo. If you ship apps with an AI builder, the vibe-coded app security checklist covers the wider habits. For more on agents in general, see the AI agents hub.