Claude Code Skills: The Complete Guide (2026)

Claude Code skills are the simplest way to teach Claude a repeatable procedure once and never explain it again. A skill is a folder with a SKILL.md file inside it: a short description of when to use it, followed by the instructions Claude should follow. Claude reads the descriptions of all your skills at startup, then pulls in the full instructions only when your request actually calls for them.

That "load on demand" design is the whole point. You can accumulate dozens of skills covering your deployment process, your code-review checklist, your database migration steps, or your house style, and none of them cost meaningful context until the moment they are relevant. This guide explains what Claude Code skills are, how they work under the hood, how to write your own, and how to install skills other people have built.

Key Takeaways

If you remember nothing else:

• A Claude Code skill is a directory containing a SKILL.md file, plus optional scripts, templates, and reference files
• Skills use progressive disclosure: only the name and description load at startup; the full body loads when Claude decides the skill is relevant, and bundled files load only when referenced
• Claude invokes a skill automatically when your request matches its description, or you can run it directly by typing /skill-name
• Skills live at four scopes: personal (~/.claude/skills/), project (.claude/skills/), plugin, and enterprise — with a clear precedence order
• Custom commands have merged into skills — a file in .claude/commands/ and a skill in .claude/skills/ both create the same slash command
• Skills follow the open Agent Skills standard and work across Claude.ai, Claude Code, the Agent SDK, and the Claude Developer Platform

Table of Contents

1. What Are Claude Code Skills?
2. Skills vs. Commands, Subagents, MCP, and Plugins
3. How Skills Work: Progressive Disclosure
4. Anatomy of a SKILL.md File
5. Where Skills Live
6. How Claude Decides to Use a Skill
7. Creating Your First Skill
8. Supporting Files, Scripts, and Dynamic Context
9. Bundled Skills That Ship with Claude Code
10. Installing Skills: Marketplaces and Plugins
11. Best Practices
12. Skills Worth Knowing in the Ecosystem
13. Conclusion

What Are Claude Code Skills?

So what are skills in Claude Code? At the simplest level, a skill is a packaged procedure that extends what Claude can do. You create a SKILL.md file with instructions, and Claude adds it to its toolkit. When a task matches the skill, Claude follows those instructions; the rest of the time, the skill sits idle and costs almost nothing.

The reason to reach for a skill is repetition. If you keep pasting the same checklist, the same multi-step procedure, or the same set of conventions into chat, that is a skill waiting to be written. It is also the right home for anything in your CLAUDE.md that has grown from a fact ("this project uses Postgres") into a procedure ("here is how we run a migration"). Unlike CLAUDE.md, which loads in full on every session, a skill's body loads only when it is used — so long reference material stays free until you need it.

Concretely, a skill is a folder:

summarize-changes/
├── SKILL.md          # required: description + instructions
├── reference.md      # optional: detailed docs, loaded on demand
├── examples/
│   └── sample.md     # optional: example output
└── scripts/
    └── validate.sh   # optional: a script Claude can execute

Only SKILL.md is required. Everything else is there to make the skill more capable without bloating what Claude has to read up front.

Claude Code skills follow the open Agent Skills standard, which means the same skill format works across multiple AI tools — not just Claude Code, but also Claude.ai, the Claude Agent SDK, and the Claude Developer Platform. Write a skill once and it travels.

Skills vs. Commands, Subagents, MCP, and Plugins

"Skill" is one of several extension mechanisms in Claude Code, and the overlap causes real confusion. Here is how they relate:

The most important clarification: custom commands have merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. Existing .claude/commands/ files keep working, but skills are now the recommended form because they add supporting files, invocation control, and automatic loading.

The relationship between skills and plugins matters too: a skill is a single capability, while a plugin is a distribution package that can bundle many skills together with other extensions. If you want the full decision framework, see our dedicated breakdown of Claude Code skills vs. plugins vs. agents vs. MCP, and our complete guide to Claude Code plugins for the packaging side.

How Skills Work: Progressive Disclosure

The mechanic that makes skills scale is progressive disclosure — loading information in three levels, only as deep as the task requires.

1. Level 1 — Metadata. At startup, only the name and description of every installed skill load into Claude's context. This is enough for Claude to recognize that a skill exists and when it might apply, at a cost of a line or two per skill.
2. Level 2 — Instructions. When your request matches a skill's description, Claude loads the full SKILL.md body and follows it. This is where the actual procedure lives.
3. Level 3+ — Resources. If the SKILL.md references bundled files (a long API reference, an example set, a script), Claude reads or runs those only when it needs them.

This is why you can install a large library of skills without slowing Claude down or draining your context window. A hundred skills might add a few thousand tokens of descriptions at Level 1, while their full bodies — potentially hundreds of thousands of tokens combined — stay on disk until called.

There is one budget worth knowing: skill descriptions share a context allowance that scales with the model's context window (roughly 1% by default). If you install a very large number of skills, Claude may shorten the least-used descriptions to fit. Running /doctor shows how many descriptions are being trimmed, and the combined description plus when_to_use text for any single skill is capped at 1,536 characters in the listing — so put the key use case first.

Anatomy of a SKILL.md File

Every skill is a SKILL.md file with two parts: YAML frontmatter between --- markers, and a Markdown body with the instructions.

---
name: api-conventions
description: API design patterns for this codebase. Use when writing or reviewing API endpoints.
---

When writing API endpoints:
- Use RESTful naming conventions
- Return a consistent error envelope: { error: { code, message } }
- Validate every request body before touching the database

Only the description is really recommended — it is what Claude matches against. Everything else is optional configuration. The most useful frontmatter fields:

The body is just Markdown — write it the way you would brief a teammate. One discipline matters: keep it concise. Once a skill is invoked, its rendered content stays in context for the rest of the session, so every line is a recurring token cost. State what to do, not how or why, and move long reference material into separate files. A good rule of thumb is to keep SKILL.md under 500 lines.

Where Skills Live

Where you save a skill determines who can use it. There are four scopes:

Use personal skills for your own cross-project habits (your commit style, your preferred research workflow). Use project skills for anything the whole team should share — commit .claude/skills/ to version control and every collaborator gets them automatically. Use plugins to distribute skills beyond a single repo.

When two skills share a name, precedence is enterprise → personal → project, and any of them overrides a bundled skill of the same name. Plugin skills sidestep collisions entirely with a plugin-name:skill-name namespace. In a monorepo, Claude also discovers skills from nested .claude/skills/ directories, so a package can ship skills that only activate when you are working inside that package.

The command you type comes from the directory name, not the frontmatter — .claude/skills/deploy-staging/SKILL.md becomes /deploy-staging. For the full walkthrough of adding skills at each scope, see how to add skills to Claude Code.

How Claude Decides to Use a Skill

There are two ways a skill runs, and understanding both is key to using skills well.

Automatic (model-invoked). The skills Claude Code loads on its own are chosen by semantic matching. Claude reads your request, compares it against every skill's description, and loads the best match. This is semantic matching, so the quality of your description is everything. A vague description like helps with code will rarely trigger. A specific one like Use when the user runs the test suite and tests fail triggers reliably because it names the exact situation.

Direct (user-invoked). You type /skill-name and Claude runs that skill immediately, no guessing involved. This is the right choice for anything with side effects — deploys, commits, sending messages — where you want to control the timing.

You can shape which path applies with two frontmatter fields:

• disable-model-invocation: true — only you can invoke it. Claude will never decide to run /deploy on its own.
• user-invocable: false — only Claude can invoke it. Useful for background knowledge (like "how our legacy billing system works") that is not a meaningful command for a human to type.

If a skill is not triggering when you expect, the fix is almost always the description: add the keywords you would naturally say, and confirm the skill is loaded by asking Claude "what skills are available?" The full playbook lives in our guide to using skills in Claude Code.

Creating Your First Skill

Here is the smallest useful skill: one that summarizes your uncommitted changes and flags anything risky. It pulls your live git diff into the prompt before Claude reads it, so the summary is grounded in your actual working tree.

1. Create the skill directory in your personal skills folder:

mkdir -p ~/.claude/skills/summarize-changes

2. Write SKILL.md at ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

3. Test it. Open a git project, make a small edit, and start Claude Code. Ask a question that matches the description — "What did I change?" — and Claude loads the skill automatically. Or invoke it directly with /summarize-changes.

That is the entire loop: a folder, a SKILL.md, a description, and instructions. The !`git diff HEAD` line is dynamic context injection, which we cover next. When you are ready to build more sophisticated skills — with arguments, bundled scripts, and evals — see our full tutorial on creating a Claude Code skill.

Supporting Files, Scripts, and Dynamic Context

Three features turn a basic skill into a powerful one.

Supporting files. Reference other files from SKILL.md and Claude loads them only when needed. This keeps the main file focused while letting a skill carry large reference docs, API specs, or example collections:

## Additional resources
- For the complete field reference, see [reference.md](reference.md)
- For worked examples, see [examples.md](examples.md)

Bundled scripts. A skill can ship a script in any language and have Claude run it rather than read it. This is the most efficient pattern for deterministic work — data processing, file generation, validation — because the script does the job without loading its code (or its output data) into context. Reference the script with the ${CLAUDE_SKILL_DIR} variable so the path resolves whether the skill is installed personally, in a project, or in a plugin:

python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

Dynamic context injection. The !`command` syntax runs a shell command before the skill content reaches Claude, and substitutes the output in place. Claude receives real data, not the command:

## Pull request context
- Diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

Skills also support string substitutions like $ARGUMENTS (everything typed after the skill name), $0 / $1 for positional arguments, and variables such as ${CLAUDE_PROJECT_DIR} and ${CLAUDE_SESSION_ID}. Together these let a single skill adapt to whatever you throw at it. See more annotated skill examples for patterns you can copy.

Bundled Skills That Ship with Claude Code

Claude Code includes a set of skills in every session — you have probably already used some. Unlike built-in commands that run fixed logic, bundled skills are prompt-based: they hand Claude detailed instructions and let it orchestrate the work.

You invoke them exactly like any other skill, and you can override any of them by creating a skill of the same name in your project — a code-review skill in .claude/skills/ replaces the bundled /code-review. If you ever need to turn the built-ins off, the disableBundledSkills setting does it.

Installing Skills: Marketplaces and Plugins

You do not have to write every skill yourself. The ecosystem distributes skills through plugins and marketplaces, and installing them is a one-line command.

Skills are shared at three scopes: project skills (commit .claude/skills/ to your repo), plugins (a skills/ directory inside a plugin), and managed deployment for whole organizations. Plugins are the main way third-party skills travel. For example, the official skill-creator plugin — which scaffolds and evaluates skills for you — installs from the official marketplace:

/plugin install skill-creator@claude-plugins-official

If Claude Code says the plugin is not found, refresh the marketplace with /plugin marketplace update claude-plugins-official (or add it first with /plugin marketplace add anthropics/claude-plugins-official), then run /reload-plugins.

Beyond the official marketplace, a growing set of community directories index thousands of skills. We cover how to browse, install, and publish through them in our Claude skills marketplace guide, and the full plugin-side workflow lives in the Claude Code plugins guide. If you are new to AI-assisted development in general, our roundup of the best AI tools for coding puts Claude Code in context.

Best Practices

A few habits separate skills that fire reliably from ones that gather dust:

• Write the description for the trigger, not the feature. Name the situation ("when a migration fails") and the words a user would actually say. Claude matches on this, so it is the highest-leverage line in the file.
• Keep the body short. It stays in context once invoked. Push long reference material into supporting files that load on demand.
• One skill, one job. A focused skill triggers more predictably than a sprawling one. Split multi-purpose skills apart.
• Guard side effects. Add disable-model-invocation: true to anything that deploys, commits, or sends — you decide when those run, not Claude.
• Evaluate, don't assume. Seeing a skill trigger is not the same as it working. Run the same prompt with and without the skill and compare; the skill-creator plugin automates this A/B loop.

For the complete checklist with examples of good and bad descriptions, see our Claude Code skills best practices guide.

Skills Worth Knowing in the Ecosystem

The community has built a deep catalog of skills. A few have become near-standard:

• Superpowers — a composable, multi-agent development framework (brainstorming, planning, TDD, review) and the largest community skill library in the ecosystem.
• Frontend Design — pushes Claude to produce distinctive, production-grade interfaces instead of generic "AI slop," and one of the most-installed skills anywhere.
• GSD (Getting Stuff Done) — a spec and context stabilizer that keeps long-running work from drifting.
• skill-creator — the official skill that interviews you, scaffolds the folder, writes the SKILL.md, and runs evals.

These are a starting point, not a ranking. For our tested, regularly updated shortlist with install commands and honest keep-or-skip verdicts, see the best Claude Code skills roundup.

Conclusion

Claude Code skills are deceptively simple: a folder, a SKILL.md, a good description. But that simplicity is the feature. Progressive disclosure means you can build a library of dozens of skills — your conventions, your procedures, your team's hard-won knowledge — and pay for them only when they are used. Custom commands folding into skills, the open Agent Skills standard, and a fast-growing marketplace mean the format is now the default way to extend Claude.

Start with one skill for something you explain to Claude more than once. Write the description for how you would ask, keep the body tight, and let Claude load it when the moment comes. From there, the rest of this cluster — creating skills, installing from the marketplace, and the best skills to try — builds on exactly what you set up here.

Related Resources

• Best Claude Code Skills (2026): Tested & Ranked
• How to Use Skills in Claude Code
• How to Add Skills to Claude Code
• How to Create a Claude Code Skill
• Claude Code Skills Best Practices
• Claude Code Skills vs. Plugins vs. Agents vs. MCP
• Claude Code Plugins: The Complete Guide
• Claude Skills Marketplace: Find, Install & Publish