A Claude Code skill is a folder. Inside it sits a file called SKILL.md with a short YAML header and some Markdown instructions. That's the whole idea. When your request matches the skill's description, Claude reads the file and follows what it says — your conventions, your steps, your gotchas. The rest of the time the file just sits there, costing nothing.
That simplicity is why Skills took off. You don't write code, register a server, or learn an API. You write down how you'd explain a task to a new teammate, save it as SKILL.md, and Claude picks it up. Ever found yourself pasting the same long instructions into Claude Code every day? A skill kills that habit.
This guide covers what Skills actually are, how they differ from MCP servers and subagents, the anatomy of a real SKILL.md, how to build and install one, and where to find skills worth stealing.
What are Claude Code Skills, exactly?
A skill is a directory containing a SKILL.md file. The file has two parts: YAML frontmatter (a name and a description) and a Markdown body with instructions. Optionally the folder holds scripts, templates, or reference docs the instructions point to.
Here's the key mechanic — progressive disclosure. Claude doesn't load every skill into context up front. At the start of a session it reads only the name and description of each available skill. That's a few dozen tokens each. When your request matches a description, Claude then reads the full SKILL.md, and only then pulls in any scripts or files it references. Three layers, loaded only as needed.
Why does that matter? Context is finite and expensive. If Claude loaded ten full skills every session, your window would fill with instructions you don't need for the task at hand. Progressive disclosure means you can have fifty skills installed and pay the token cost only for the one that fires.
Skills are also model-portable. The same SKILL.md works whether you run Sonnet, Opus, or Haiku — it's plain text, not code bound to an API. Point Claude Code at any compatible endpoint and your skills travel with the project.
How do Skills differ from MCP servers and subagents?
People mix these up constantly. They solve different problems.
- Skills add knowledge and procedure — how to do a task, in text Claude reads on demand.
- MCP servers add tools and data — they connect Claude to external systems (a database, an issue tracker, a browser) through a running process.
- Subagents add isolation — a separate context window where a delegated task runs without polluting your main conversation.
A quick comparison:
| Skill | MCP server | Subagent | |
|---|---|---|---|
| What it adds | Instructions / workflow | Tools, external data | Separate context |
| Format | SKILL.md folder | Running server (stdio/HTTP) | Agent config + prompt |
| Loaded | On demand (progressive disclosure) | Connected at startup | Spawned per task |
| Needs code? | No | Usually | No |
| Best for | Repeatable procedures | Live data, side effects | Parallel or noisy work |
They compose. A skill can tell Claude to call a tool from an MCP server, then hand off to a subagent. Think of Skills as the playbook, MCP as the equipment, subagents as extra hands. For the tooling side, see /blog/mcp-servers-claude-guide.
What does a real SKILL.md look like?
Minimal but complete. Here's a skill that standardizes pull-request descriptions:
---
name: pr-description
description: >
Write a pull request description for the current branch. Use when
the user asks to "open a PR", "write a PR description", or
"summarize this branch for review".
---
# PR description
Generate a PR description from the diff against the base branch.
## Steps
1. Run `git diff main...HEAD` to see all changes on the branch.
2. Group changes by intent, not by file.
3. Write the description with these sections:
- **What** — one-paragraph summary of the change.
- **Why** — the problem it solves or the ticket it closes.
- **How to test** — concrete steps a reviewer can run.
- **Risks** — anything that could break, or "none".
4. Keep it under 250 words. No filler. Use present tense.
## Conventions
- Reference issues as `Closes #123`.
- If the diff touches `migrations/`, add a **Migration** note.
- Never include generated lockfile changes in the summary.
Two things make this work. The description is specific about when to use the skill — it lists the actual phrases a developer types. Vague descriptions ("helps with PRs") don't fire reliably; concrete trigger phrases do. And the body reads like onboarding notes: numbered steps, hard rules, edge cases.
The frontmatter only requires name and description. Everything else is instruction.
How do you create a Claude Code skill?
Five steps. You can build a useful one in under ten minutes.
1. Make the folder. Project-level skills live in .claude/skills/; user-level skills (available in every project) live in ~/.claude/skills/. Name the folder after the task:
mkdir -p .claude/skills/pr-description
2. Write SKILL.md with frontmatter. Open .claude/skills/pr-description/SKILL.md and add the YAML header. Spend the most effort on the description — that single field decides whether the skill ever fires.
3. Write the instructions. Below the frontmatter, write the workflow in plain Markdown. Imagine explaining the task to a competent new hire who doesn't know your conventions yet.
4. Add scripts or resources (optional). If the task needs a template or a helper script, drop it in the same folder and reference it:
Use the template at `./templates/pr-body.md` as the starting structure.
Claude reads that file only when the skill activates — progressive disclosure again.
5. Test it. Start a session and trigger the task:
claude
> open a PR for this branch
If Claude picks up the skill, you'll see it follow your steps. If it doesn't, your description is probably too vague or doesn't match how you phrased the request. Tighten it and retry.
A few rules that keep skills reliable:
- One skill, one job. Don't cram "PRs and commits and changelogs" into one file. Split them.
- Front-load the trigger. The
descriptionshould name the situations and phrases that should activate it. - Keep the body short. A focused skill of 30–80 lines beats a 300-line manual Claude has to wade through.
- Version it with the repo. Commit project skills to git so the whole team gets them.
How do you install and invoke a skill?
Installing is just putting the folder in the right place. No build step, no restart of a server. Drop your-skill/SKILL.md into .claude/skills/ (this project) or ~/.claude/skills/ (every project) and it's live next session.
Invoking is usually automatic. You describe the task; Claude matches it against skill descriptions and loads the best fit. That's the whole point of the design — you don't memorize commands.
| Scope | Path | Available in |
|---|---|---|
| Project | .claude/skills/ | Just this repo (commit to share) |
| User | ~/.claude/skills/ | Every project on your machine |
| Plugin | shipped via a plugin/marketplace | Wherever the plugin is installed |
Plugins are how skills travel between people. A plugin can bundle several skills (plus commands and agents) and install them in one step from a marketplace. That's the distribution layer on top of the plain-folder format.
Where do you find the best Claude Code skills?
Three sources, roughly in order of polish:
- Plugin marketplaces. Curated bundles you install with one command. They package skills with commands and subagents so a whole workflow drops in together.
- Community collections on GitHub. Search "claude code skills" or "everything claude code" and you'll find repos that collect dozens of skills — frontend design, code review, doc writing, testing, refactoring. Read the
SKILL.mdbefore installing; you're handing these instructions to your agent. - Your own team. The best skills are the ones encoding your conventions. Marketplaces give you a starting kit; your real wins come from skills nobody else could write.
Skills worth having early:
- frontend-design — house rules for components, spacing, tokens, accessibility, so generated UI matches your system.
- code-review — your review checklist as a skill: what to flag, severity levels, what to ignore.
- doc-writing — tone, structure, and examples so generated docs read like the rest of your handbook.
- testing — your test conventions: framework, naming, coverage expectations, fixtures.
One caution: a skill is instructions you hand to an autonomous agent. Treat third-party skills like any dependency — read them first. A skill that tells Claude to run shell commands deserves the same scrutiny you'd give any script.
Running Claude Code + Skills from Russia or anywhere
Skills are pure text, so they work regardless of where you run Claude Code. The friction is usually billing and access, not the feature itself.
If you can't open an Anthropic account — no US card, no appetite for a VPN — Claudexia is a gateway to Claude with pay-per-token pricing from $0.33 per 1M tokens. Point Claude Code at the Claudexia endpoint and Skills, MCP servers, and subagents all work the same:
export ANTHROPIC_BASE_URL="https://api.claudexia.tech"
export ANTHROPIC_API_KEY="sk_cdx_yourkeyhere"
No Anthropic account, no VPN, no monthly minimum — top up, get a sk_cdx_… key, and your .claude/skills/ folder behaves exactly as it would on the direct API. Setup details: /blog/claude-code-russia-setup and the full /blog/claude-code-setup-guide.
FAQ
Do Claude Code Skills cost extra tokens?
Only when they fire. At session start Claude reads just the name and description of each skill — a tiny cost. The full SKILL.md and any referenced files load only when the skill matches your task. That's progressive disclosure, and it's why you can keep many skills installed without bloating context.
Are Skills the same as MCP servers? No. Skills add instructions Claude reads on demand; MCP servers add tools and live data through a running process. A skill can tell Claude to use an MCP tool, but they're separate layers. See /blog/mcp-servers-claude-guide for the tooling side.
Where should I put a skill — project or user level?
Put team conventions in .claude/skills/ and commit them so everyone gets them. Put your personal habits in ~/.claude/skills/ so they follow you across every project. Plugins cover wider distribution.
Why isn't my skill activating?
Almost always the description. Claude matches your request against it, so it must name the actual situations and phrases that should trigger the skill. Rewrite it to be concrete ("use when the user asks to open a PR"), not vague ("helps with git").
Can I use Skills without an Anthropic account?
Yes. Skills are a Claude Code feature, not an account feature. Run Claude Code through Claudexia with a sk_cdx_… key — no Anthropic signup, no VPN — and Skills work normally. Start at /docs/quickstart.
Start building
Skills turn the instructions you keep repeating into something Claude loads on its own. Write one this week — a PR description, a review checklist, your test conventions — and you'll stop pasting the same prompt twice.
Get Claude Code wired up in the /docs/guides/claude-code guide, or go straight to /docs/quickstart. For comparisons see /blog/claude-code-vs-cursor-2026, and for common questions, /docs/faq.