Claude Code Skills: The Complete Guide

What Are Claude Code Skills?

A Claude Code skill is a packaged, reusable capability that bundles a workflow into a folder Claude can load when it is relevant. Think of it as a saved playbook: a named procedure, a description of when to use it, the step-by-step instructions, and any supporting files. The skill sits on disk until a request lines up with what it does, and then Claude follows it.

The point of a skill is to encapsulate something you would otherwise repeat. If you find yourself pasting the same setup notes, the same conventions, or the same multi-step checklist into Claude over and over, that is a skill waiting to be written. Once it exists, the knowledge stops living in your head or in a stale doc and starts living somewhere Claude can act on it.

Three properties make skills different from just writing a long prompt:

• They are discoverable. Claude knows a skill exists and what it is for, so it can reach for the right one without you naming it.
• They are progressive. Only the short description stays in context all the time. The full instructions and any attached files load only when the skill is actually used, which keeps your context lean.
• They are portable. A skill is a folder, so it lives in version control, travels with the repo, and can be shared across a team or across every project you touch.

Skills do not change what Claude is capable of. They change how reliably it does a known task. A model that can write tests already exists; a skill makes it write tests your way, with your framework, your folder layout, and your naming conventions, every single time, without you re-explaining.

How Skills Work

The mechanics of Claude Code skills come down to one question: how does Claude decide to use one? The answer is the description. Each skill exposes a short name and description that stay available to Claude at all times. Those summaries are the routing layer. When your request matches one, Claude loads the rest of the skill.

The Invocation Flow

Here is what happens, step by step, when you make a request:

1. You send a request. You describe a task in plain language, the same way you always would.
2. Claude scans the skill descriptions. It compares your intent against the name and description of every available skill.
3. A match loads the full skill. If a description fits, Claude reads that skill's complete instructions and any files it references.
4. Claude follows the workflow. It executes the steps the skill defines, using its normal tools along the way.
5. No match means business as usual. If nothing fits, Claude just answers the way it normally would.

This is why the description is the most important line in a skill. It is doing the matching. A vague description like "helps with deployment" will fire at the wrong times or fail to fire at all. A precise one like "use when deploying the static site to Hostinger after a build" gives Claude a clean trigger.

Why This Saves Context

The progressive loading is the quiet win. Imagine ten skills, each with a thousand words of detailed instructions. If all of that lived in context all the time, you would burn a large chunk of your window before doing any work. Instead, only the short descriptions are resident. The heavy instructions and attached resources load on demand, for the one skill that actually applies.

That keeps the main thread clean and leaves more room for the code and conversation that matter. It is the same principle that makes a well-structured CLAUDE.md valuable: put the right information where Claude can reach it, but do not force everything into context at once.

Skills vs Subagents vs MCP vs Slash Commands

This is where most of the confusion lives. Claude Code has four extension mechanisms that sound similar but solve different problems. Mixing them up leads to building the wrong thing. Here is the clean distinction, then a side-by-side table.

• A skill changes how a task is done. It is instructions Claude follows in the current context.
• A subagent changes who does the task. It is a separate worker with its own context window.
• An MCP server changes what Claude can reach. It connects Claude to external tools and data.
• A slash command changes when a prompt fires. It is a manual trigger you type yourself.

The key insight is that these are not alternatives competing for the same job. They stack. A skill can tell Claude to call an MCP server as one of its steps. A subagent can follow a skill while it runs in its own context. A slash command and a skill can wrap the same procedure, one for when you want to fire it manually and one for when you want Claude to reach for it on its own.

How to Create a Skill

Creating a skill is mostly writing. You make a folder, drop in a SKILL.md, and fill it with a name, a description, and instructions. The skill becomes available the next time Claude looks at your skills directory.

Where Skills Live

Skills sit in a skills directory as one folder per skill. You have two main homes for them:

• Project skills live inside the repository. They travel with the codebase, get reviewed in pull requests, and are shared by everyone who clones the repo. Use these for workflows specific to that project, like its deploy process or its test conventions.
• Personal skills live in your user-level Claude configuration directory. They follow you across every project. Use these for habits you want everywhere, like the way you write commit messages or summarize a change.

The SKILL.md Structure

A skill folder is just a directory with a Markdown file at its root. The file opens with a small block of metadata, then the instructions. The shape looks like this:

skills/
└── run-tests/
    ├── SKILL.md          # name + description + instructions
    ├── reference.md      # optional supporting doc
    └── check-coverage.sh # optional helper script

And the SKILL.md itself follows a predictable pattern: a name, a description that does the matching, and the step-by-step body.

---
name: run-tests
description: Use when running or fixing the test suite for this
  repo. Runs the project's tests, reports failures, and follows
  our coverage rules before claiming a pass.
---

# Running the Test Suite

1. Run the full suite with the project's test command.
2. If a test fails, read the failure, fix the cause, and re-run.
   Do not edit the test to make it pass.
3. Confirm coverage stays above our threshold before reporting.
4. Report the actual command output, not a summary you assume.

Adding Scripts and Resources

Because a skill is a folder, you can include more than instructions. Drop in a helper script the workflow runs, a template the output should match, a checklist Claude should walk through, or a schema file it should validate against. The SKILL.md points to these files, and Claude pulls them in only when the skill runs. That keeps the always-loaded description small while still giving the workflow everything it needs at execution time.

Example Skills Worth Building

The best skills come from your own repetition. If you have explained something to Claude twice, write it down as a skill the third time. To get you started, here are categories of Claude Code skills that pay off quickly across most teams.

Notice the pattern: each example is a procedure with a right answer your team already knows. The skill is just where that answer lives so Claude applies it consistently. If a workflow changes every time you do it, it is not a skill yet. Skills are for the things that should be the same every time.

Skills + Agent Teams

Skills and subagents are not rivals. They are layers of the same system. A subagent decides who handles a piece of work and keeps its context isolated; a skill decides how that work gets done. Put them together and you get a team where every member does its specialized job the right way.

Picture a five-agent team: an orchestrator that plans and delegates, a researcher that maps the code, an implementer that writes the change, a reviewer that checks it against the plan, and a shipper that runs the final test-build-deploy gate. Each of those roles benefits from skills:

• The implementer follows your "new component" skill so every file lands in the right place with the right conventions.
• The reviewer follows your "code review" skill so it checks the same standards every pass instead of guessing.
• The shipper follows your "deploy" skill so the release sequence never gets improvised under pressure.

The division of labor matters because each subagent runs in its own context window. The researcher's large codebase sweep never pollutes the implementer's context, and a skill loaded inside the implementer's window stays scoped to that worker. You get specialist focus per step, clean main-thread context, and consistent execution from the skill, all at once.

If you want the full multi-agent setup as a starting template, our Claude Code agent team starter pack gives you the five-agent structure and the config files to drop into any repo, with skills layered in where they make each role sharper.

Best Practices

A few habits separate skills that earn their keep from skills that sit unused or, worse, fire at the wrong moment. These hold up across projects and team sizes.

1. Write the Description for the Trigger, Not the Feature

The description decides when the skill loads, so write it from the angle of "when should Claude reach for this?" A description that names the situation, the inputs, and the goal will match cleanly. One that only restates the title leaves Claude guessing.

2. One Skill, One Workflow

Keep each skill scoped to a single repeatable procedure. A skill that tries to cover deployment and testing and review will have a muddy description and fire unpredictably. Split it. Sharp boundaries make matching reliable.

3. Avoid Overlapping Descriptions

If two skills have similar descriptions, Claude may pick the wrong one. Make sure each skill's trigger is distinct. When you notice yourself unsure which of two skills should run, that is a sign their descriptions need tightening.

4. Keep the Always-Loaded Part Small

Push detail into the body and into attached files, not the description. The description is resident in context; the rest loads on demand. A long description costs you context on every session for a skill that may not even run.

5. Put Project Skills in Version Control

A project skill belongs in the repo so it is reviewed, shared, and versioned with the code it describes. When the deploy process changes, the skill changes in the same pull request. That keeps the playbook and the reality in sync.

6. Start Small and Let Patterns Emerge

Do not try to skill-ify everything on day one. Write skills for the two or three procedures you repeat most, then add more only when a real pattern shows up. A handful of sharp skills beats a pile of overlapping ones every time. For more on structuring the surrounding setup, see how skills pair with CLAUDE.md project memory and how the whole toolkit compares in our Claude Code vs Cursor breakdown.

Frequently Asked Questions