How Claude Code Skills Actually Work

Most people who first hear “Claude Code Skills” assume they are a fancier system prompt — a longer, more polished version of the instructions you’d normally paste at the top of a chat. That mental model is wrong in a way that matters.

A skill is a folder, not a paragraph

A Skill is a directory on disk: a SKILL.md file with a name and description in its frontmatter, plus whatever reference files, scripts, or templates the task needs. Claude Code reads only the frontmatter of every installed skill up front — a name and a one-line trigger condition. The full body of a skill’s instructions loads only when Claude decides the task at hand matches that trigger.

This is the part that changes how you should think about them: you can install fifty skills without paying for fifty skills’ worth of context. The frontmatter index costs a few tokens each. The actual instructions — which might reference a 2,000-word checklist or a Python script that does deterministic work — only load when relevant, and only for the skills that matched.

Why that matters more than the prompt itself

A system prompt is loaded every single turn, whether or not it’s relevant to what you just asked. A skill is loaded conditionally, on the model’s own judgment about whether the current task matches the trigger. That means:

• You can encode narrow, opinionated procedures — “how we do database migrations here,” “the exact checklist for a security review” — without bloating every unrelated conversation.
• Skills can bundle actual code (a validation script, a linter, a data transform) that Claude runs rather than reasons about from scratch, which is more reliable for anything with a deterministic right answer.
• Because triggering is based on a written description, a skill that never fires is usually a description problem, not a model problem — the fix is rewriting the trigger condition, not rewriting the instructions.

The practical upshot

If you keep re-explaining the same procedure to Claude Code in every session, that is exactly the shape of thing a skill should absorb. Write it once, give it a clear name and a description of when it applies, and stop paying the “re-explain” tax on every new conversation.