Claude Code Skills: The Complete Guide to SKILL.md

What are Claude Code skills?

A skillis, in Anthropic’s words, an organized folder of instructions, scripts, and resources that an agent can discover and load dynamically to perform better at a specific task. In Claude Code the framing is more concrete: you create a SKILL.mdfile with instructions, and Claude adds it to its toolkit. Claude uses the skill when it’s relevant, or you invoke it directly with /skill-name.

Anthropic launched Agent Skills in October 2025 and released the format as an open standard in December 2025, so the same SKILL.md works across Claude.ai, Claude Code, the Agent SDK, the API, and partner platforms. The mental model: a general-purpose agent plus a library of skills becomes a specialized one, without you re-explaining the same procedure every session.

Skills vs CLAUDE.md vs subagents vs MCP vs plugins

The fastest way to understand skills is to place them next to the things they’re often confused with. They’re all ways to shape what Claude Code does, but they solve different problems.

Anthropic’s one-liner is worth memorizing: MCP is for connectivity, skills are for procedural knowledge, and subagents are for independent execution. A useful tie-breaker between CLAUDE.md and a skill: if a section of your CLAUDE.md has grown from a fact into a multi-step procedure, it wants to be a skill. For the full format-by-format breakdown, see SKILL.md vs CLAUDE.md vs .cursorrules vs AGENTS.md.

The SKILL.md format

A skill is a directory; SKILL.md is its required entry point. The file has two parts: YAML frontmatter between --- markers, and a Markdown body. Here is the minimal valid skill:

---
name: summarize-changes
description: Summarize what changed in the working tree. Use when the user
  asks "what did I change?", wants a PR description, or a diff summary.
---

# Summarize changes

## Instructions
1. Run `git diff` (and `git diff --staged`) to see the changes.
2. Group the changes by area and intent, not file-by-file.
3. Write a tight summary: what changed and why it matters.

## Output
A markdown summary with an H2 per area and a one-line TL;DR at the top.

Across every surface, only two fields are required:

• name — up to 64 characters, lowercase letters, numbers, and hyphens only. It can’t contain the reserved words “anthropic” or “claude”.
• description — up to 1024 characters, written in the third person, stating both what the skill does and whento use it. This is the single most important line in the file, because it’s what triggers the skill.

Claude Code extendsthe open standard with a set of optional fields. You rarely need most of them, but they’re the difference between a note and a real automation:

Supporting files

A skill can bundle more than SKILL.md. The convention is a flat folder with reference docs and a scripts/ directory:

my-skill/
├── SKILL.md          # required entry point
├── reference.md      # detailed docs, loaded only when needed
├── examples.md       # usage examples, loaded only when needed
└── scripts/
    └── helper.py     # executed by Claude — its code never enters context

Where skills live

Skills are filesystem-based in Claude Code. Where you put the folder decides who gets the skill:

When names collide, precedence is enterprise › personal › project. Plugin skills are namespaced (plugin-name:skill-name), so they never conflict. Project skills load from .claude/skills/ in the start directory and every parent up to the repo root, which makes them monorepo-aware.

How skills are triggered: progressive disclosure

The core architectural idea — and the reason you can install dozens of skills without bloating your context — is progressive disclosure. Content loads in three levels:

So a skill can carry a huge reference file or a complex script that costs nothinguntil the moment it’s needed — load what matters, when it matters, which is the whole idea behind context engineering for AI coding agents. There are two ways a skill loads:

• Description-based auto-invocation— Claude reads the always-in-context descriptions and pulls in the skill when a request matches. Asking “what did I change?” auto-loads a summarize-changes skill.
• Explicit invocation — type /skill-name (with arguments via $ARGUMENTS). This bypasses matching entirely.

How to create a skill

The manual path is just a folder and a file:

mkdir -p ~/.claude/skills/summarize-changes
$EDITOR ~/.claude/skills/summarize-changes/SKILL.md
# edits under ~/.claude/skills/ take effect within the session —
# no restart needed (unless you're creating the skills dir for the first time)

The guided path is the official skill-creator skill, which interviews you, drafts the SKILL.md, generates test cases, runs with-skill vs without-skill baselines, grades the result, and packages it. Invoke it with /skill-creator. It’s the fastest way to a production-ready skill, and it bakes in Anthropic’s evaluation-driven approach.

Best practices Anthropic recommends

• Be concise.“The context window is a public good.” Assume Claude is already smart; add only what it doesn’t know.
• Keep the body under ~500 lines and split overflow into separate reference files, one level deep.
• Write descriptions in the third person, specific, with the trigger terms a user would actually say. “Extract text and tables from PDF files… use when the user mentions PDFs” beats “Helps with documents.”
• Set the right degrees of freedom — prose for open-ended tasks, exact scripts for fragile or destructive ones.
• Name with a gerund (processing-pdfs, reviewing-prs); avoid helper or utils.
• Develop with evals. Write 3+ test scenarios and measure a baseline without the skill before you trust it.

The skills ecosystem

The reference implementation is anthropics/skills, which holds the spec, a template, and example skills (the docx, pdf, pptx, and xlsx document skills, plus skill-creator and mcp-builder). Beyond that, community “awesome” lists and third-party marketplaces collect thousands of skills. The problem most teams hit isn’t finding skills — it’s managing them once they have a dozen across several machines and repos.

Managing skills as your library grows

A single skill is a folder. Twenty skills, spread across your personal ~/.claude/skills/, three repos’ .claude/skills/, and a teammate’s machine, is a version-control problem. Which version of code-review is authoritative? Did the fix you made in one repo make it into the others? And if you also use Cursor or Copilot, the same standards now live in .cursorrules and copilot-instructions.md too.

That’s the gap Skillwrightfills: hold your skills in one canonical library, version them once, and compile + deploy to every IDE and every project from a single place. If you’re running more than one AI coding tool, start with how to manage AI coding rules across tools and the cross-tool AGENTS.md standard. You can also grab six MIT-licensed starter skills from the templates library.

Frequently asked questions