What are Claude Code skills?

What a skill actually changes

Anthropic's documentation is blunt about the trigger: when you keep pasting the same instructions, checklist or multi-step procedure into the chat, write a skill. The same page adds a second tell that is easy to miss. When a section of CLAUDE.md has stopped being a fact and turned into a procedure, it belongs in a skill too.

The difference from CLAUDE.md is not length, it is when the text loads. CLAUDE.md rides along every turn. A skill does not: Claude gets the name and one description line, and the body shows up only when the skill is invoked, either by you typing /skill-name or by Claude deciding the request matches.

A skill is a directory, not a paragraph. The shape the docs show:

my-skill/
├── SKILL.md        required: overview and navigation
├── reference.md    API details, read only when needed
├── examples.md     usage samples, read only when needed
└── scripts/
    └── helper.py   executed, not loaded into context

Three parts, three jobs. The frontmatter decides when the skill becomes visible, the body is the procedure Claude follows, and the bundled files are the deep reference the body points at. The docs recommend keeping SKILL.md under 500 lines and moving detail into separate files.

The three loading stages

This is the part worth understanding before you install anything, because it explains both why skills are cheap and why they fail.

Idle. Only the name and description of each skill sit in context. That list is not free: it gets a budget scaled to about 1% of the model's context window, and when the list overflows, Claude Code drops descriptions from the skills you use least.

Invoked. The rendered SKILL.md enters the conversation as one message and stays across later turns. It is not re-read from disk, so write instructions that hold for the whole task, not one-shot steps.

On demand. Reference files are read when Claude needs them, and scripts are executed rather than loaded. A 300-line API reference costs nothing until it is opened. The same 300 lines pasted into the body cost you every turn.

One compression detail matters more than it looks. When a long conversation is summarized, Claude Code re-attaches each invoked skill's most recent call, keeping the first 5,000 tokens of each, under a shared 25,000-token budget filled from the most recent call. With many skills in one session, an early one can vanish entirely.

Where skills come from

The phrase "Claude skills" covers three different supply lines. Mixing them up is where most confusion starts.

• Anthropic's own repository

  anthropics/skills had 182,075 stars on 2026-10-19, with 19 skill folders under skills/, including docx, pdf, pptx, xlsx, skill-creator, mcp-builder, frontend-design and webapp-testing. Sessions signed in with a claude.ai account sync some of these automatically; pdf and xlsx always sync.

• What ships with Claude Code

  Bundled skills such as /doctor, /code-review, /debug, /batch, /loop, /claude-api, /run and /verify. They are prompt-based: detailed instructions that steer Claude's own tools. One setting, disableBundledSkills, turns the whole set off.

• Community installs

  Mostly through the cross-agent installer, npx skills add <owner/repo> from vercel-labs/skills: 35,548 stars, MIT, created 2026-01-14, npm package 1.7.2, listing 40+ supported agents. The other layer is awesome-style directories, for example ComposioHQ/awesome-claude-skills at 53.4k stars. A directory measures how many people saved a link, not whether it works.

The practical split: Anthropic's set is general capability. Your project's conventions are not in it and never will be. That part goes in a project skill or in CLAUDE.md, and it is the only layer you can actually keep current.

Are skills plugins?

No, and the difference is architectural rather than cosmetic. A skill is one folder of instructions plus whatever it ships alongside. A plugin is a directory with a manifest, usually .claude-plugin/plugin.json, that can contain skills, agents, hooks, MCP servers and hook modules, installed and loaded as one unit.

The docs are explicit that the components do not need the package. Skills, subagents, hooks and MCP servers all work standalone. A plugin earns its place when you want to install someone's whole setup in one command, or hand the same setup to a team and keep it updated as a versioned release.

That packaging has a price you pay on every turn. Once a plugin is enabled, the name and description of each of its skills, agents and auto-invocable commands sit in context for every session, whether or not anything runs. Anthropic's marketplace shows a context cost estimate before you install for exactly this reason.

Four things people confuse

The first three columns below come from the docs. The last one, common misuse, is my read of those mechanics rather than documentation text.

Skills vs MCP

This is the choice that actually bites. Skill or server is not a matter of taste, it is a matter of what you are missing: a procedure, or a connection.

1. Procedure or data? Steps, review criteria, commit conventions and style rules are procedure, so a skill. Reading a Postgres table or opening a pull request is data and action, so an MCP server.
2. Are you copying from another tool into the chat? That is the official signal to connect a server. You are paying a human tax to move bytes that a server could move.
3. Must this happen every time, without the model remembering? Then it is a hook, not a skill. Hooks run on their event whether or not Claude follows anything.
4. Is the output long and disposable? Send it to a subagent. Its context is separate and only the summary comes back.
5. One procedure or a set of components? One procedure, write a skill. Several components with an update cadence, consider a plugin.

They compose. An MCP server supplies tools, a skill supplies the order to use them. A skill can tell Claude to check the issue first, then edit, then open the pull request, while the tools come from the server. Anthropic's own mcp-server-dev plugin makes the point: the plugin is the package, the guidance inside it is a skill.

What the official docs already say

Honest answer first: Anthropic maintains a full official docs set for skills, including a Simplified Chinese translation. Every frontmatter field, seven loading locations, troubleshooting entries, the description budget: all there, and not badly written. The mechanism paragraphs on this page are checked against those pages on 2026-10-19.

So this page deliberately does not repeat them. No field tables, no install walkthrough, no "ten tips". Install steps live on the install page. What is left here is the part the docs assume you already figured out: which of these four things you actually need.

When a skill is the wrong choice

• The rule must fire every time. Use a hook. A skill depends on the model following it, and compression can drop it entirely.
• You need live data or a write path. Use an MCP server. A skill is files; it cannot query your database.
• The output is noisy and used once. Use a subagent. You want isolation, not reuse.
• It is three sentences for one person. Put it in CLAUDE.md. A skill pays off through repeated use and on-demand loading. If you have neither, the folder is overhead.
• You have not written it three times by hand yet. Do that first. A skill freezes a procedure; freezing a bad one just makes it reproducible.

Four ways skills break

1. Descriptions get trimmed and nothing triggers. The list is capped around 1% of the context window and Claude Code removes the least-used descriptions first, keywords included. /doctor estimates the list cost; /skill-doctor reports which skills were actually used.
2. Broken frontmatter still loads, but dead. If the YAML fails to parse, Claude Code loads the body with every field empty: /skill-name works, and auto-invocation never does. Run with --debug, or validate the folder with claude plugin validate.
3. Compression eats the early skill. After summarization only recent calls survive, first 5,000 tokens each, 25,000 total. Keep the load-bearing instruction near the top of SKILL.md.
4. It is hidden behind disable-model-invocation. That flag keeps the description out of context. Fine for a deploy step you invoke on purpose, fatal for anything you expect Claude to notice by itself.

What this page does not know

Everything else is checkable: the loading rules, budgets, install locations and plugin behaviour come from the pages linked below, read on 2026-10-19. Star counts and folder counts come from the GitHub API on the same date. Recheck the docs rather than trusting this page after a release or two.

• Skills vs plugins: which one to install

  Six differences, three combinations, and what each wrong choice costs per turn.

  Choosing · 2026-10

• Which skills are worth installing

  Picked by scenario, not by star count, with the case for skipping each one.

  Shortlist · 2026-10

• Installing skills: three routes and the errors

  Project or personal folder, the cross-agent installer, the plugin route.

  Install · 2026-10

Sources

• Claude Code docs: skills: file structure, frontmatter, loading locations and precedence, description budget, content lifecycle, troubleshooting.
• Claude Code docs: plugins: components, standalone versus packaged, context cost, install scopes.
• Claude Code docs: MCP: what servers add, install scopes, tool search, prompt injection warning.
• Claude Code docs: subagents: separate context, definition locations, tool limits.
• anthropics/skills: 182,075 stars and 19 skill folders as of 2026-10-19, from the GitHub API.
• vercel-labs/skills: 35,548 stars, MIT, created 2026-01-14, as of 2026-10-19.