Claude Skills for Developers: The Complete Guide

Skills are the highest-leverage thing a developer can add to Claude, and the least understood. They are not a plugin API, not a framework, and not a prompt library. A skill is a markdown file that teaches Claude a capability once, then loads itself automatically whenever a task matches. This is the developer's guide: how they work, where they fit among the other extension points, and how to roll them out on a team without creating a mess.

The mechanism, in one section

A skill is a folder containing SKILL.md: YAML frontmatter with a name and a description, then markdown instructions, plus any scripts or reference files it wants to bundle. It lives in .claude/skills/ inside a project, or ~/.claude/skills/ for every project on your machine.

The important part is progressive disclosure. Claude does not load your skills into context. It loads only their names and descriptions — roughly a sentence each. When a task matches a description, the full body is pulled in and followed. This is why a library of a hundred skills costs almost nothing until one is needed, and why the description is the single most important line in the file: it is the only thing Claude sees when deciding whether the skill is relevant.

The corollary catches everyone at least once. A skill with a vague description is not a weak skill — it is an invisible one. It never loads, and because nothing errors, you assume it is working. Descriptions must name situations: "Use before opening a PR, when the user asks for a review, or after finishing a feature" rather than "code review expertise". Our triggering guide covers this in depth, and the free SKILL.md validator catches the mechanical errors.

Skills versus everything else

Four extension points, one sentence each. CLAUDE.md is always-on context: facts true of every task in the repo. Skills are on-demand procedures: loaded when relevant, free when not. Subagents are delegation: a separate context window for work that would otherwise pollute yours. MCP servers are connectivity: running processes that expose tools connecting Claude to databases, APIs, and systems.

The distinction that matters most: skills teach, MCP connects. A skill can explain exactly how to write a safe migration; it cannot reach your database. An MCP server can reach your database; it has no opinion about what a safe migration looks like. Used together, they are a complete capability. We compare all four in detail in skills vs subagents vs slash commands vs MCP.

The pattern that separates good skills from bad

Let the model decide; let the code execute. Anthropic's open-source document skills demonstrate this: the markdown handles judgment — which branch applies, what the user actually wants — and bundled scripts handle everything with a single correct answer, like extracting a table or filling a form. Deterministic work belongs in code. Asking a language model to do it in prose produces output that is usually right, which is the worst possible reliability profile.

The second pattern: state the prohibitions. The most valuable lines in most skills are negative — do not patch the symptom, do not refactor beyond the request, do not invent findings when the diff is clean. Skills exist precisely because some default behavior was wrong, and naming it is the whole point.

Rolling skills out on a team

Commit them. A skill in .claude/skills/ arrives with the repository, so every teammate — and every new hire on day one — gets the same review checklist, the same migration rules, the same deployment process. Changes go through pull requests like any other code, which means your engineering standards become reviewable artifacts instead of folklore.

That reframes what a skill is for. The tempting first skills are generic ones — testing, review, debugging — and those are worth having. But the highest-value skill on any team is the one nobody else could write: how your deployment works, why your team rejected a library, which directory owns what. That knowledge currently lives in senior engineers' heads and gets rediscovered painfully. A skill is the place to put it.

Where skills come from

Three routes. Write your own, which is the only way to capture project-specific knowledge. Copy from GitHub, where the supply is enormous and unvetted — read our GitHub sourcing guide, and read the skills themselves, because they run with your permissions. Or install a plugin from a marketplace, which bundles skills, agents, and commands together with updates; our marketplace guide explains how that works.

Where to start this week

Write one skill for the thing you correct Claude about most often. Use it for a week, and every time you have to correct it again, add a line. That feedback loop is the entire method — after a few rounds you have a document encoding your actual standards rather than someone else's idea of best practice. Then repeat for the next most annoying thing.

FAQ

Keep reading