Claude Code Skills: What They Are, What They Cost

Part of the reduce Claude Code token usage pillar, which covers every lever that moves your bill. This page is narrower: what skills and plugins add to your context, and why they're rarely the reason it's full.

What is a Claude Code skill?

A skill is a markdown file that teaches Claude Code how to do a specific job, which it then invokes on its own when the task matches. You write SKILL.md, drop it in a folder, and from that point Claude can reach for it without you asking — that's the whole idea, and it's what separates a skill from a slash command you have to remember to type. Concretely, a skill is a directory containing a required SKILL.md plus any supporting files it needs (templates, examples, scripts). It lives in one of three places:

.claude/skills/<name>/SKILL.md — project scope, committed with the repo
~/.claude/skills/<name>/SKILL.md — personal scope, follows you across projects
<plugin>/skills/<name>/SKILL.md — bundled in a plugin, namespaced as /plugin-name:skill-name

The file is YAML frontmatter plus markdown instructions. The fields worth knowing:

Field	What it does
`name`	The skill's identifier
`description`	When Claude should use it — this is the part that lives in your context
`disable-model-invocation`	Set `true` and Claude won't auto-select it; you invoke it yourself
`user-invocable`	Set `false` to hide it from the `/` menu
`allowed-tools`	Tools pre-approved for this skill, cleared once it finishes
`hooks`	Inline event handlers (PreToolUse, PostToolUse, …)

What does a skill actually look like?

Smaller than you'd expect. Here's a complete, working one — .claude/skills/release-notes/SKILL.md:

---
name: release-notes
description: >
Draft release notes from the commits since the last tag. Use when the
user asks for a changelog, release notes, or "what shipped".
allowed-tools: Bash(git log:), Bash(git tag:)
---

Read the commits since the most recent tag with `git log <tag>..HEAD --oneline`.

Group them under Added / Changed / Fixed. Skip merge commits and anything
touching only CI config — those aren't news to a user.

Write in past tense, one line per change, no commit hashes. If a change is
user-visible, lead with what the user can now do, not what the code does.

That's the whole file. No registration step, no config to edit — Claude picks it up from the directory. Two things this example is doing deliberately. The description names the trigger conditions ("when the user asks for a changelog…"), not the implementation, because that field is all Claude has to decide on. And allowed-tools narrows the blast radius to two read-only git commands, so a skill about writing text can't wander into your working tree.

How does Claude decide to use a skill?

It reads the description field and judges whether it fits the task in front of it. That's the mechanism, and it has one consequence people miss: for Claude to choose a skill, it has to know the skill exists — so every skill's description is loaded into your context at session start. Which makes description-writing the entire craft of authoring a skill. Compare:

# Claude picks this for everything, or for nothing
description: Helps with database work.

# Claude can actually make a decision on this one
description: >
Write and review Postgres migrations. Use when the user adds a column,
changes a type, or asks whether a migration is safe on a live table.

The second one names situations, not capabilities. That's the difference between a skill that fires when you need it and one you end up invoking by hand anyway — and if you're invoking it by hand, you wanted a slash command. The full skill content is not loaded up front. That loads only when the skill is actually invoked. Anthropic documents this deferral explicitly as a context-efficiency measure, and it's the right design: you pay a small standing cost for discoverability and the large cost only on use. Worth being precise about what is and isn't documented here. The deferred-loading behaviour is documented. The exact reasoning by which Claude picks one skill over another is not — it happens inside the model, and anyone telling you they've reverse-engineered the heuristic is guessing. And I could find no published figure for what a skill description actually costs in tokens; they're short markdown, so it's small, but "small" is not a number and I'd rather say so than invent one.

What's the difference between skills, plugins, MCP and hooks?

This is where most confusion lives, so here's the one-line version of each:

Thing	What it is	Reach for it when
Skill	Instructions Claude discovers and invokes on its own	You want Claude to pick a workflow without being told
Plugin	A versioned bundle of skills, agents, hooks and MCP servers	You're sharing extensions across a team or many repos
MCP server	An integration exposing external tools (GitHub, Postgres…)	Claude needs to call a service you don't own
Hook	A command that fires around Claude's actions	You want automation around the work — lint after edits, load secrets at start
Subagent	An isolated agent with its own context and tools	A subtask would otherwise bloat your main conversation
Slash command	A fixed, direct invocation	You want a button, not a decision

The useful distinction: a skill is something Claude chooses, a slash command is something you press, and a hook is something that fires whether anyone chose it or not.

What is a Claude Code plugin?

A plugin is a self-contained, versioned directory that bundles extensions so they can be shared and version-controlled — which loose .claude/ files can't be. One plugin can carry skills, custom agents, hooks, MCP servers, LSP servers, background monitors, output styles, default settings, and binaries that get added to the Bash PATH. It's identified by a manifest at .claude-plugin/plugin.json:

{
"name": "unique-identifier",
"description": "What this plugin does",
"version": "1.0.0",
"author": { "name": "Your Name" }
}

Installing one is two steps — add a marketplace, then install from it:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install <name>@<marketplace-name>
/reload-plugins

A marketplace is just a catalogue: a git repo, local directory or URL hosting a marketplace.json. Anthropic runs a curated claude-plugins-official (available automatically) and a screened claude-plugins-community. You can host your own for a team, which is the actual reason plugins exist — distribution, not capability.

What do skills and plugins cost you in context?

Here's the part that matters if you're watching your bill or your usage limit, and it's genuinely good news with one catch. Skills are cheap by design. Descriptions at session start, content on demand. Install twenty skills and you pay twenty short descriptions, not twenty full playbooks. Plugins are cache-friendly. Skills, agents, hooks and themes from a plugin are appended after the cached prompt prefix, so enabling or disabling one doesn't invalidate your prompt cache. That's a bigger deal than it sounds: cache invalidation means re-paying full price for context you'd already bought. MCP servers are the exception, and the catch. On supported models, MCP tools are deferred by default — only tool names sit in context, and full definitions load when a tool is actually used. That's cache-safe. But when deferral isn't available (some providers and custom gateways don't support tool search), every tool definition lands in the system prompt instead. That's both expensive and cache-invalidating: connecting or disconnecting such a server forces a cache rebuild. So the practical hierarchy, cheapest first: skills and hooks are close to free, plugins are free to toggle, and MCP servers are the thing to audit — especially if you've connected several and never checked whether they're deferring. The standing cost is real but small. The cost that actually shows up on your invoice is elsewhere: the files your agent reads, the command output it swallows whole, and the conversation replayed on every turn. A single "fix this test" prompt is forty tokens of your words and tens of thousands of tokens of context. No amount of skill hygiene touches that.

How to apply this today

Write skills, not slash commands, for anything repetitive. If you'd have to remember to type it, Claude won't use it when you're tired. A description is the whole interface.
Keep descriptions tight. They're the part that's always resident. One clear sentence about when to use the skill beats a paragraph about what it does.
Use disable-model-invocation: true for skills you only ever run manually. It takes the description out of Claude's view entirely — the only lever that removes the standing cost.
Audit your MCP servers before your skills. That's where the context actually goes. Disconnect the ones you connected once and forgot.
Then fix the real bill. How to reduce Claude Code token usage covers the levers that move the number: retrieval instead of whole-file reads, filtering noisy output, structure before bodies.

If you'd rather not do step 5 by hand, that's what Tokenade does — it sits between the agent and its tools and applies those levers automatically, including folding third-party MCP results at the boundary. On the open token optimizer benchmark it cuts session cost by 39% on long sessions against running no tool at all.

What goes wrong (anti-patterns)

Writing a skill with a vague description. Claude selects on the description alone. "Helps with testing" will be picked for everything or nothing. Installing plugins you don't use. Cheap is not free, and every skill description is resident. A tidy /plugin list is worth ten minutes a quarter. Blaming skills for a big bill. They're the wrong suspect. Check what your agent is reading before you audit what it's loading. Assuming every MCP server defers. It depends on model and provider support. If your context feels heavy after connecting a server, that's the first thing to test.

See also:

Best MCP servers for Claude Code — the servers worth the context they take
Token-efficient MCP tool use — cutting manifest cost specifically
Claude Code pricing — what the bill is actually made of
Claude usage limits explained — why the ceiling arrives sooner than you expect

Sources: Skills · Plugins · Plugin marketplaces · Prompt caching and context loading · How Claude Code works