If you keep pasting the same instructions into Claude Code — your team’s commit message format, the steps for cutting a release, the rules your code reviewer always enforces — a Skill turns that into something Claude reaches for on its own. A Skill is a small folder with a SKILL.md file inside. Claude reads the short description, and when your request matches, it pulls in the full instructions.
The point is repeatability without the token tax. Claude only loads the heavy instructions when they’re actually relevant, so you can keep a stack of skills around without bloating every prompt. This is the cleanest way to encode “how we do things here” so the agent stops guessing.
This guide covers what a Skill is, the exact SKILL.md format, where the files go, how Claude loads them, and a small working example you can copy.
What a Skill actually is
A Skill is a directory. The only required file is SKILL.md, which has YAML frontmatter at the top and Markdown instructions below it. The frontmatter carries two key fields:
SKILL.md frontmatter
| name | Short identifier for the skill |
|---|---|
| description | One or two sentences telling Claude when to use it |
The body is plain Markdown — the instructions Claude follows once the skill is active. That can be a checklist, a procedure, formatting rules, or pointers to other files in the same folder. A skill can also ship supporting files: a script, a template, a reference document Claude reads when needed.
The description does the heavy lifting. It’s the part Claude scans to decide whether the skill applies, so it has to name the trigger clearly. “Helps with code” is useless. “Reviews Python pull requests for security issues and style violations” tells Claude exactly when to reach for it.
Where Skills live
There are two locations, and the difference is scope.
Skill locations
| .claude/skills/ | Project skills — committed to the repo, shared with the team |
|---|---|
| ~/.claude/skills/ | User skills — personal, follow you across every project |
On Windows the user path is C:\Users\YourName\.claude\skills\. Each skill gets its own subfolder, and the folder name is how you’ll refer to it:
.claude/
skills/
pr-review/
SKILL.md
release-notes/
SKILL.md
template.mdProject skills are the right call for anything team-specific — they live in version control, so everyone who clones the repo gets them. User skills are for your own habits that don’t belong to any single project, like a personal commit-message style.
How Claude loads them on demand
This is the part that makes Skills cheap to keep around. Claude doesn’t read every skill’s full instructions on startup. It reads only the name and description from each SKILL.md — a few lines — which costs very little context. The body stays on disk until it’s needed.
When your request matches a description, Claude loads that skill’s full instructions into the conversation. This staged loading is sometimes called progressive disclosure: the lightweight metadata is always available, the expensive detail arrives only when relevant. You can have a dozen skills installed and pay almost nothing for the ones you’re not using right now.
The practical consequence: the description isn’t documentation, it’s a trigger. If a skill never seems to activate, the description is usually too vague or doesn’t mention the words you actually use when asking.
Invoking a Skill
Most of the time you don’t invoke a skill at all — you describe the task, and if the description matches, Claude pulls the skill in. Ask it to “review this PR for security issues” and a well-described pr-review skill loads on its own.
You can also be explicit. Skills surfaced as commands are called with a slash, the same way other slash commands work:
/pr-reviewSlash commands and skills overlap here, so it’s worth knowing the distinction. A custom slash command is a prompt you trigger by name, every time, on purpose. A skill is something Claude can choose to apply when it fits — and can also be invoked directly. If you want a procedure that only ever runs when you explicitly call it, a slash command is the simpler tool. If you want Claude to apply a process automatically whenever a task matches, a skill is the better fit. The full mechanics of /name commands are in the slash commands docs.
A worked example
Here’s a complete, minimal skill that standardizes commit messages. Create the folder and file:
.claude/skills/commit-style/SKILL.md---
name: commit-style
description: Use when writing git commit messages. Enforces Conventional Commits format with a scope and an imperative subject line under 72 characters.
---
# Commit message style
When asked to write or suggest a commit message, follow these rules:
1. Use the Conventional Commits format: `type(scope): subject`.
2. Allowed types: feat, fix, docs, refactor, test, chore, ci.
3. The scope is the affected area in lowercase, e.g. `auth`, `api`, `docker`.
4. Write the subject in the imperative mood ("add", not "added").
5. Keep the subject line under 72 characters. No trailing period.
6. Add a body only when the change needs context — wrap it at 72 columns.
## Example
feat(auth): add token refresh on 401 responses
Retries the original request once after refreshing the access token, so users no longer get logged out on transient expiry.
Drop that in, then ask Claude to write a commit message for your staged changes. Because the description names the trigger — writing git commit messages — Claude loads the skill and follows the rules. No pasting, no reminding.
Set up your first skill
- Create .claude/skills/
/ in your project - Add SKILL.md with name and a trigger-focused description
- Write the instructions as plain Markdown below the frontmatter
- Ask Claude to do the matching task and confirm the skill loads
- Commit project skills so the team shares them
Portable across Claude tools
Skills aren’t locked to the terminal. The Agent Skills format is shared, so the same SKILL.md folder works across Claude tools that support skills. You can author a skill once and reuse it — a pr-review skill you built for the CLI carries over rather than needing a rewrite. That portability is a reason to keep skills small and self-contained.
Where to go next
A Skill is the right tool when you have a repeatable process you keep explaining. Start with one — your commit style, your review checklist — confirm it triggers, then add more as you spot the patterns you repeat.
When you’re ready to build your own from scratch, see how to write a Claude Code Skill. To understand where skills fit next to other extension points, read Skills vs MCP vs Subagents. And for skills worth installing or copying, see the best Claude Code Skills for 2026.
