What Are Claude Code Skills? A Practical Explainer

A Claude Code skill is a folder containing a SKILL.md file: YAML frontmatter that says what the skill is for, followed by Markdown instructions that tell Claude how to do one job well. Claude keeps only each skill’s name and description in context, loads the full instructions when your request matches, and can pull in bundled scripts, references, and templates as the task needs them. You get a reusable playbook, such as a code review checklist, a migration procedure, or a PDF toolkit, that costs almost nothing until it is used.

This guide covers how skills work under the hood, what a real SKILL.md looks like, how Claude decides to use one, and when a skill is the right tool compared with CLAUDE.md or a one-off prompt.

How do Claude Code skills work?

Skills rely on a loading model called progressive disclosure. Instead of putting everything into the context window at startup, Claude Code loads a skill in three layers:

Layer	What loads	When	Typical cost
1. Metadata	name and description from the frontmatter	Every session, at startup	About 100 tokens per skill
2. Instructions	The Markdown body of SKILL.md	When the skill is invoked	Keep under 500 lines, around 5k tokens
3. Resources	Files in references/, scripts/, assets/	Only when the instructions point to them and the task needs them	Scripts run; only their output enters context

Layer 1 is how Claude knows the skill exists. When you ask for something, Claude compares your request against the descriptions it has seen. If one matches, it invokes the skill, and the body of SKILL.md is added to the conversation, where it stays for the rest of the session. If the body says “for the full list of lock-safe DDL patterns, read references/ddl.md,” Claude reads that file only when it reaches that step.

Scripts are the most token-efficient part. When a skill tells Claude to run scripts/validate.py, the script executes and only its output enters context. A 400-line validator costs a few lines of output instead of 400 lines of code.

Long sessions get compacted. After auto-compaction, Claude Code re-attaches the most recent invocation of each skill you used, up to the first 5,000 tokens per skill within a 25,000-token shared budget, so a skill you invoked an hour ago does not silently vanish.

What does a SKILL.md file look like?

Here is a small but complete skill. It lives at ~/.claude/skills/pr-summary/SKILL.md:

---
name: pr-summary
description: Writes a pull request title and description from the current branch's diff, grouping changes by intent and flagging risky edits. Use when the user asks to write, draft, or update a PR description, or says "open a PR".
---

# PR summary

## Context
- Current branch: !`git branch --show-current`
- Diff stat against main: !`git diff --stat main...HEAD`

## Steps
1. Read the full diff with `git diff main...HEAD`.
2. Group changes by intent (feature, fix, refactor, chore), not by file.
3. Write a title under 70 characters in the imperative mood.
4. In the body, list risky changes first: migrations, auth, public API, config.
5. End with a "How to test" section with concrete commands.

Never invent ticket numbers. If the branch name contains one, use it.

Three things to notice:

1. The folder name matches name. The open standard requires the name field to match the parent directory, and to use lowercase letters, digits, and single hyphens.
2. The description does two jobs. It says what the skill does and when to use it. Claude reads only this text when deciding whether to load the skill, so it carries the trigger phrases.
3. The !`command` lines are dynamic context. Claude Code runs these commands before Claude sees the skill and replaces each one with its output. The skill arrives already knowing the branch name and diff stat.

Larger skills add supporting files:

schema-migrations/
├── SKILL.md            # overview and workflow, loaded on invocation
├── references/
│   ├── postgres.md     # loaded only for Postgres work
│   └── mysql.md        # loaded only for MySQL work
└── scripts/
    └── check_locks.sh  # executed, never read into context

For the full list of frontmatter fields, see the SKILL.md format reference.

How does Claude decide when to use a skill?

There are two ways a skill gets invoked:

• Automatically. Claude matches your request against skill descriptions and loads the one that fits. Ask “why is this test flaky?” with systematic-debugging installed and Claude can pick it up without being told.
• Manually. Every skill also becomes a slash command. Type /pr-summary or /schema-migrations add a NOT NULL column to orders and the skill loads with whatever you typed after the name available as $ARGUMENTS.

You can restrict either path. disable-model-invocation: true makes a skill manual-only, which suits anything with side effects, such as a deploy or release skill you never want triggered by accident. user-invocable: false hides a skill from the / menu so only Claude can invoke it, which suits background knowledge that is not a meaningful command.

Automatic invocation is only as good as the description. “Helps with databases” will either never trigger or trigger for everything. “Plans zero-downtime Postgres migrations… Use when renaming or dropping columns, adding NOT NULL…” triggers on the right requests. If a skill is not firing, the description is the first thing to check; the troubleshooting guide covers the rest.

Where do skills live?

Location	Path	Applies to
Personal	~/.claude/skills/<name>/SKILL.md	All your projects
Project	.claude/skills/<name>/SKILL.md	Anyone working in that repo
Nested	<subdir>/.claude/skills/<name>/SKILL.md	Loaded when you work in that subdirectory
Plugin	<plugin>/skills/<name>/SKILL.md	Wherever the plugin is installed, invoked as /<plugin>:<name>
Enterprise	Managed by your organization	Everyone in the org

When two skills share a name, enterprise wins over personal, and personal wins over project. Plugin skills are namespaced, so they never collide. The personal vs project skills guide goes into precedence and when to choose each.

Edits are picked up live. Change a SKILL.md under ~/.claude/skills or your project’s .claude/skills and the next invocation uses the new version without restarting Claude Code. Run /skills to see what is loaded.

When should you use a skill instead of CLAUDE.md or a prompt?

Skills, CLAUDE.md, and plain prompts overlap. The deciding question is how often the knowledge is needed and how big it is.

Use	Best for	Why
A prompt	One-off tasks	No setup; nothing to maintain
CLAUDE.md	Facts every session needs: build commands, repo layout, code style	Always loaded, so keep it short
A skill	Procedures and domain knowledge needed some of the time	Loads on demand, can bundle scripts and references

A useful heuristic: if you have pasted the same multi-paragraph instructions into a chat three times, it should be a skill. If Claude needs a fact in nearly every session, such as “run tests with pnpm test,” it belongs in CLAUDE.md. If you are putting a 300-line release checklist into CLAUDE.md, you are paying for it in every session, including the 95% that have nothing to do with releases. Move it to a skill. The memory-file-architect skill helps split an overgrown CLAUDE.md into exactly this shape.

Skills also beat prompts when the work has deterministic parts. A prompt can ask Claude to check a migration for table locks; a skill can ship a script that does the check the same way every time.

Other Claude Code features solve different problems. Hooks enforce rules deterministically, subagents give a task its own context window, and MCP servers connect to live external systems. The skills vs commands, subagents, and MCP comparison maps each one.

What kinds of skills are worth installing?

The best skills encode judgment Claude would not apply consistently on its own. A few examples from this directory:

• Workflow discipline. systematic-debugging forces reproduce, isolate, and verify before any fix. tdd-loop keeps Claude on red-green-refactor. commit-craft produces atomic commits with useful messages.
• Review checklists. code-review and owasp-review turn a vague “look this over” into a structured pass with severity levels.
• Domain playbooks. schema-migrations and postgres-indexing carry the kind of operational detail that is easy to get wrong under pressure.
• File toolkits. pdf-toolkit and xlsx-spreadsheets bundle scripts for document work that a model should not improvise.
• Meta skills. skill-authoring helps you write your own, and skill-description-tuning fixes skills that trigger at the wrong time.

Skills are not limited to Claude Code. The format is an open standard published at agentskills.io, and the same folder can be uploaded to claude.ai or the Claude API as long as it sticks to the standard fields. The skills on claude.ai and the API guide explains what carries over.

Are skills safe?

A skill is code and instructions that run with your permissions. Scripts execute, and !`command` lines run shell commands before Claude even reads the skill. Treat installing a skill like adding a dependency: read the SKILL.md and every bundled file first. Every skill page on this site shows the full SKILL.md and all supporting files before you download, and the skill safety guide lists what to look for.

Next steps

• Install your first skill: How to install Claude Code skills
• Learn every frontmatter field: SKILL.md format reference
• Build one from scratch: Write your first Claude Code skill
• Browse the full directory: /skills/, or start with the workflow and claude-code categories
• Official documentation: code.claude.com/docs/en/skills