Claude Code skills: when to use them and when they pile up as overhead

A Claude Code skill is a folder with one file inside. That file is called SKILL.md. It opens with YAML frontmatter (a name and a description) and then a markdown body. Claude loads the body into context only when the description matches what the user just asked for. That on-demand loading is the whole point.

The trap is that skills look like CLAUDE.md content that learned to wait its turn. CLAUDE.md ships with every prompt. Skills sit on a shelf and only show up when Claude judges them relevant. That sounds free. It is not. A skill description runs about 75 to 150 tokens once wrapped in XML, and at the default budget Claude Code keeps roughly 15 to 25 skill descriptions discoverable on a 200K context window before truncation starts dropping some of them. Every skill is a slot another skill cannot occupy.

This is the trade-off most teams miss when they ship their first batch of skills. The piece below walks through four situations where a skill earns its slot, and four where it costs more than it returns.

When skills earn their place

Use a skill when the procedure runs longer than five lines

If you keep pasting the same five-step recipe into chat, the recipe belongs in a skill. Examples: set up the test database with these env vars, seed it with these fixtures, run this exact npm command, parse the output like this, write the assertion in that style. The body of the skill can run hundreds of lines without bloating any session that does not need it. The cost is the description in the listing, not the body. A long body that fires once a week is cheap; the same body pasted into CLAUDE.md is expensive every prompt forever.

Use a skill when the workflow only fires sometimes

A PR review checklist runs once per PR. A changelog generator runs at release. A migration writer runs when the schema moves. None of these belong in CLAUDE.md, because CLAUDE.md loads on every prompt, and carrying a release-time procedure through every code edit costs real tokens against the weekly cap. A skill loads only on the prompts where the description matches, which means the migration writer stays asleep through the 200 unrelated tasks between schema changes.

Use a skill when you keep correcting the same library

Any library that shipped a major version in the last twelve months will produce code from training data that is partially wrong. Next.js 16, the Anthropic SDK, Prisma, most Vercel tooling. A skill that captures the current API plus three gotchas (renamed exports, changed defaults, deprecated patterns) keeps Claude on the new version without you retyping the same correction every session. The win compounds: every team member on the repo gets the same fix without sharing a doc.

Use a skill when multiple agents need the same expertise

Security review procedures, data analysis methods, accessibility audits. If the same body of knowledge needs to live in three subagents, it should live in one skill that all three pull. Subagents are about isolating context and tool permissions. Skills are about packaging reusable expertise. The split matters when the team grows past one engineer and one project: a subagent that bakes security review into its own prompt locks that logic to one task, while a skill makes it available to any task that mentions security.

When skills become overhead

Skip the skill when the rule applies to every task

"Always use feat:, fix:, chore: prefixes in commit messages." "Never edit files under src/legacy/." "Run npm run typecheck before claiming a task is done." These are CLAUDE.md content, not skills. A skill loads only when its description matches the prompt, which means a project-wide rule wrapped in a skill will silently miss the prompts where it was supposed to apply. CLAUDE.md never misses. That is its job. Putting an always-on rule behind a fuzzy match is how you find out the rule was off the whole time.

Skip the skill when the team is one person and one project

If you are a solo engineer with one repo, the slot economy does not bite yet. Almost everything fits in CLAUDE.md without compaction pain. Skills become valuable when the procedure either grows past what CLAUDE.md can hold cheaply, or needs to be shared across repos and people. A solo project rarely hits either threshold. Forcing the structure early adds a folder layer without buying anything back, and the cognitive cost of remembering which procedure lives where is real.

Skip the skill when the description is vague

The description is the trigger. Claude does fuzzy matching against that string, and a description like "helps with database tasks" will silently never fire because nothing the user types overlaps it. Anthropic's own authoring guide tells you to lead with the verb a user would actually say ("Create, update, or list scheduled tasks…"), then the noun, then the conditions. The official advice goes further: be a little pushy, because Claude tends to undertrigger skills it could have used. If the description reads like marketing prose, the skill is dead weight in the listing and Claude keeps doing the wrong thing because it never saw the skill fire.

Stop carrying skills you no longer use

The default skill-listing budget is one percent of the context window. On a 200K window that holds 15 to 25 descriptions before truncation starts dropping skills you might have needed. Every skill kept around is a slot another skill cannot fill, and if the budget is raised enough to fit all of them, the bill can hit 300K extra prompt tokens per week on a Pro plan just to surface the directory. Audit the list once a quarter. If a skill has not fired in three months, archive it.

How to test if a skill earned its slot

Before publishing a new skill, ask three questions.

First, would the description match a prompt the user is actually going to type? Read it cold and check it leads with a real verb. "Create scheduled tasks, update them, list them" beats "helps with scheduling" every time, because the first one shares words with how a user phrases the request.

Second, does the body push Claude past its default behaviour? A skill that reminds Claude to use useEffect is wasted; a skill that captures three gotchas from a library Claude consistently writes wrong is not. The most valuable content in any skill is information Claude would not have produced on its own.

Third, is there a Gotchas section? The most cited part of any well-built skill is the bullet list of common mistakes. Anthropic's own best-practices guide for skill authors leans heavily on this pattern. If the skill is just a tutorial, Claude can already write the tutorial. If it documents the failure modes you keep hitting, it earns its slot.

The frame to keep in mind: CLAUDE.md is for facts that apply to every task in the repo. Skills are for procedures that fire sometimes and would bloat every session if they were always on. Subagents are for tasks that need their own context window and tool permissions. Most teams reach for skills first because the folders feel clean. The clean folders cost real tokens. Use them when the procedure pays them back.

We covered the runtime side of Claude Code customisation in our piece on hooks. Skills sit one layer up: hooks intercept tool calls, skills inject expertise on demand. The two compose, and they answer different questions.

Sources

• Extend Claude with skills, Claude Code Docs
• Agent Skills overview, Claude API Docs
• Skill authoring best practices, Claude API Docs
• Equipping agents for the real world with Agent Skills, Anthropic Engineering
• Claude Code's Hidden Skill Listing Budget, ClaudeFast