Claude Code Skills: what they are and how to build your own

A Claude Code skill is a folder. In it sits a file called SKILL.md: a short YAML header and instructions in Markdown. That is where the idea ends. When your request matches the skill's description, Claude reads the file and acts on it: your conventions, your steps, your gotchas. The rest of the time the file sits idle and costs nothing.

People like Skills for their simplicity. There is no code to write, no server to run, no API to learn. You write down a task the way you would explain it to a new teammate, save it as SKILL.md, and Claude picks it up. Do you paste the same long block of instructions into Claude Code every day? A skill breaks that habit.

The order from here: what Skills really are, how they differ from MCP servers and subagents, what a working SKILL.md looks like, how to build and install your own, and where to find other people's skills worth borrowing.

What are Claude Code Skills, exactly?

A skill is a directory with a SKILL.md file in it. The file has two parts: YAML frontmatter (a name and a description) and a Markdown body with instructions. The folder can also hold scripts, templates or reference docs that the instructions point to.

The main mechanic is called progressive disclosure. Claude does not load skills into context up front. At the start of a session it sees only the name and description of each available skill, a few dozen tokens per skill. Once a request matches a description, Claude reads the whole SKILL.md. Scripts and files that it references come last. That makes three layers, each loaded only when it is needed.

Why bother? Context is finite and costs money. If ten full skills landed in every session, the window would fill with instructions that have nothing to do with the task at hand. With progressive disclosure you can keep fifty skills installed and pay tokens only for the one that fired.

Skills are also independent of the model. The same SKILL.md runs on Sonnet, Opus or Haiku: it is plain text, not code written for a specific API. Point Claude Code at any compatible endpoint and your skills move with the project.

How do Skills differ from MCP servers and subagents?

People confuse these three all the time, though they do different jobs.

• Skills carry knowledge and procedure: how to do a task, as text that Claude reads on demand.
• MCP servers supply tools and data: through a running process they connect Claude to outside systems (a database, an issue tracker, a browser).
• Subagents provide isolation: a delegated task runs in a separate context window and does not clutter the main conversation.

Side by side:

They work better together than apart. A skill can tell Claude to call a tool from an MCP server and then hand the work to a subagent. Skills are the playbook, MCP is the equipment, subagents are extra hands. The tooling side is covered in MCP servers with Claude in 2026.

What does a real SKILL.md look like?

The example is minimal but complete: 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 it work. First, the description says precisely when to use the skill and lists the actual phrases a developer types. A vague description ("helps with PRs") fires unreliably, while concrete trigger phrases fire. Second, the body reads like onboarding notes, with numbered steps, hard rules and edge cases.

Only name and description are required in the frontmatter; the rest is instruction. You can write SKILL.md in English even if you work in another language: the model understands both, and English trigger phrases often match the way teams actually word their requests.

How do you create a Claude Code skill?

There are five steps, and a useful skill takes 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. Put most of your effort into the description: that one field decides whether the skill fires at all.

3. Write the instructions. Under the frontmatter, describe the process in plain Markdown. Picture yourself briefing a capable newcomer who does not know your habits yet.

4. Add scripts or resources (optional). If the task needs a template or a helper script, put it in the same folder and point to 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. Open a session and give it the task:

claude
> open a PR for this branch

If the skill is picked up, Claude follows your steps. If not, the description is probably too vague or does not match how you phrased the request. Sharpen it and try again.

A few rules that keep skills dependable:

• One skill, one job. "PRs, commits and changelogs" in a single file is a bad mix; split it into three.
• Trigger first. In the description, name the situations and phrases that should start the skill.
• Short body. A focused skill of 30-80 lines beats a 300-line manual that Claude has to wade through.
• Versions with the repo. Commit project skills to git and the whole team gets them at once.

How do you install and invoke a skill?

Installing means putting the folder in the right place. There is no build step and no server to restart. Drop your-skill/SKILL.md into .claude/skills/ (this project) or ~/.claude/skills/ (every project), and the skill is live from the next session.

Invoking is usually automatic. You describe the task, Claude compares it with the skill descriptions and loads the best match. That is the point of the design: there are no commands to memorize.

Skills travel between people as plugins. A plugin can bundle several skills (plus commands and agents) and install them in one step from a marketplace. It is a distribution layer on top of the plain-folder format.

Where do you find the best Claude Code skills?

There are three sources, listed roughly by how polished they are:

1. Plugin marketplaces. Curated bundles that install with one command. Skills come packaged with commands and subagents, so a whole workflow arrives at once.
2. Community collections on GitHub. Searching "claude code skills" or "everything claude code" turns up repos with dozens of skills: frontend design, code review, docs, testing, refactoring. Read the SKILL.md before installing, because you are handing those instructions to your agent.
3. Your own team. The best skills capture your conventions. A marketplace gives you a starter kit, and the real payoff is in skills nobody else could write.

Skills worth having early:

• frontend-design: house rules for components, spacing, tokens and accessibility, so generated UI fits your system.
• code-review: your review checklist, meaning what to flag, which severity levels exist and what to skip.
• 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 a set of instructions you hand to an autonomous agent, so treat third-party skills like any dependency and read them first. If a skill tells Claude to run shell commands, give it the scrutiny you would give any script.

Running Claude Code with Skills from Russia or any other country

Skills are plain text, so they work wherever you run Claude Code. The friction is usually billing and access, not the feature.

If you cannot open an Anthropic account (no US card, no wish to deal with a VPN), codexkey gives access to Claude with pay-per-token pricing from $0.33 per 1M tokens. Point Claude Code at the codexkey endpoint and Skills, MCP servers and subagents all work the same:

export ANTHROPIC_BASE_URL="https://api.codexkey.online"
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 as it does on the direct API. Setup details are in the guide to installing and connecting Claude Code without an Anthropic account and the full setup guide. Questions go to the team in Telegram: https://t.me/codex_key.

FAQ

Do Skills cost extra tokens? Only when they fire. At the start of a session Claude reads just the name and description of each skill, which is a trivial cost. The full SKILL.md and any files it references load when the skill matches the task. That progressive disclosure is why you can keep many skills installed without bloating context.

Are Skills the same as MCP servers? No. Skills add instructions that Claude reads on demand, while MCP servers add tools and live data through a running process. A skill can tell Claude to use an MCP tool, but the two are separate layers. More on the tooling side in MCP servers with Claude in 2026.

Should a skill go at project or user level? Put team conventions in .claude/skills/ and commit them so everyone receives them. Keep personal habits in ~/.claude/skills/, where they follow you across projects. Plugins cover wider distribution.

Why isn't my skill activating? Almost always the description. Claude matches your request against it, so it has to name the real situations and trigger phrases. Rewrite it concretely ("use when the user asks to open a PR"), not vaguely ("helps with git").

Can I use Skills without an Anthropic account? Yes. Skills belong to Claude Code, not to an account. Run Claude Code through codexkey with a sk_cdx_… key (no Anthropic signup, no VPN) and Skills work as usual. Start with the quickstart.

Start building

Skills turn the instructions you repeat day after day into something Claude loads by itself. Write one this week (a PR description, a review checklist, your test conventions) and you will not paste the same prompt twice.

You can wire up Claude Code with the guide in the docs or jump straight to the quickstart. A comparison with the Cursor editor is in Claude Code or Cursor in 2026, and common questions are answered in the FAQ.