Claude Code Skills Explained: A Complete Guide (2026)

verified against the official docs at code.claude.com/docs/en/skills (accessed 2026-08-09).

What are Claude Code skills?

If you have used Claude Code for a while, you have probably wished it would just remember how you like a repetitive job done - "when you review code, follow this checklist," or "when you optimize an image, run exactly these commands." That is the problem skills solve.

Claude Code skills are reusable, model-invokable instruction packs - each one a folder with a SKILL.md file that tells Claude when to use it and how to do the task. Think of a skill as a laminated "how we do this job" card pinned to a wall: Claude reads the titles to know which card exists, then only pulls one down and reads the details when a task calls for it.

Every skill has two core parts:

• The description frontmatter - one short line that says what the skill does and when to trigger it. This is the part Claude always "sees."
• The markdown body - the detailed steps, conventions, and examples. This loads only when the skill is actually invoked.

Skills are not a Claude-only invention. They follow the open Agent Skills standard (agentskills.io), which means the same SKILL.md format works across different Claude surfaces and, in principle, other tools that adopt the standard. Write a skill once and you can reuse it across projects, share it with teammates, or install a whole pack of them prebuilt.

One 2026 change worth flagging up front: custom slash commands have been merged into skills. The old .claude/commands/*.md files still work, but a SKILL.md now does both jobs - Claude can auto-invoke it by description, and it also creates a matching /skill-name command. If you read a tutorial written in early 2025 that treats "commands" and "skills" as two separate systems, that is the pre-merge model.

How Claude Code skills work (progressive disclosure)

This is the most important part to understand why skills are worth it, rather than just "a tidy way to store a prompt." The mechanism is called progressive disclosure.

When Claude Code starts, it does not load the full contents of every skill into the context window. Instead it loads only each skill's short description - just enough to know "there is a code-review skill, a deploy skill, an image-optimizer skill." When a task matches one of those descriptions, Claude then reads the full body of that one skill and follows it. Supporting files (a template, a reference doc, a script) load only when the skill explicitly references them.

Here is the token-cost intuition. If you dump every convention into your CLAUDE.md, all of it sits in context on every turn - including the 90% of guidance you rarely need, and you pay tokens for it each turn. With skills, the "always-on cost" is just a few lines of description per skill; the heavy body only enters context at the moment it is needed. That is how skills let you keep a large library of instructions without bloating the context window.

A skill gets activated in one of two ways:

• Automatically - Claude matches your request against every skill's description and decides which to invoke. You do nothing except describe the task; the skill just needs a clear description.
• Manually with /skill-name - you call a specific skill directly, e.g. /code-review. Handy when you want to force Claude down an exact workflow.

Because Claude relies on the description to auto-select, the quality of that one line decides whether the skill fires at the right moment. A vague description like "helps with images" makes Claude hesitate; a trigger-rich one like "use when converting PNG to WebP and compressing under 200KB" fires almost every time.

Skills vs commands, subagents, hooks & MCP

This is where newcomers get tangled - Claude Code has a whole family of concepts that sound similar. Here is a fast comparison, one or two lines each, so you can place them:

The key distinction: a skill is markdown-plus-scripts that shapes how Claude works, while MCP is a tool protocol that gives Claude new capabilities from outside systems. They complement each other - a skill can describe how to use an MCP-connected tool well. If you want the full breakdown of where each concept begins and ends, I wrote a dedicated deep-dive: skills vs subagents vs hooks vs MCP.

Where skills live (personal, project, plugin, enterprise)

Where you put the skill folder decides its scope. Claude Code looks for skills in several locations, in priority order:

Use personal skills for your own habits across all work, and project skills for conventions that belong to a specific repo (commit .claude/skills/ and everyone on the team gets them). One nice detail: Claude Code detects changes to your skill files live - edit a SKILL.md and it picks up the new version without a restart, which makes iterating on a skill fast.

Anatomy of a SKILL.md file

At the file level, a skill is surprisingly simple: it is just a folder named with the skill's slug, containing a required SKILL.md. You can add optional supporting files - templates, scripts, examples - for the skill to reference when it runs:

~/.claude/skills/optimize-web-image/
├── SKILL.md (required)
├── template.md (optional - output template)
├── examples/ (optional - reference examples)
└── scripts/convert.sh (optional - helper script)

The SKILL.md itself is YAML frontmatter followed by a markdown body. Here is a real, runnable skill:

---
name: optimize-web-image
description: Convert a PNG to WebP and compress under 200KB. Use when the user needs to optimize an image for the web.
allowed-tools: Bash, Read
---

# Optimize web image

When asked to optimize an image:

1. Run `cwebp -q 80 input.png -o output.webp`.
2. Check the output file size. If it is still over 200KB,
 drop quality to `-q 70` and run again.
3. Report the new file path and its final size.

That is the whole thing. The frontmatter tells Claude when to use the skill; the body tells it how. Here are the frontmatter fields you will reach for most (see the official docs for the full list):

One practical rule: keep SKILL.md under roughly 500 lines. Once a skill is invoked its body enters the context and stays there for the session, so a bloated body costs you tokens - push long reference material into supporting files and point to them only when needed.

Build your first skill in 5 minutes (step by step)

Let us build a small but genuinely useful skill: summarize-changes, which turns your recent git diff into a plain-English summary. Three steps.

1. Create the folder (personal scope, so it works in every project):

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

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

   ---
   name: summarize-changes
   description: Summarize the current git changes in plain English, grouped by area. Use when the user asks what changed or wants a PR summary.
   allowed-tools: Bash, Read
   ---
   
   # Summarize changes
   
   1. Run `git diff --stat` and `git diff` for uncommitted changes.
   2. Group edits by area (feature, fix, docs, tests, chore).
   3. Write 3-6 bullet points in plain English - what changed and why
    it matters - short enough to paste into a pull request.

3. Test it two ways. Open Claude Code in a repo with some uncommitted edits and either type the command directly - /summarize-changes - or just ask naturally: "summarize what I changed." If your description is clear, the natural prompt auto-fires the skill without you naming it.

Because Claude Code detects skill files live, you do not need to restart - the skill is available the moment you save the file.

A skill in action (real example + honest take)

The summarize-changes skill above is one I actually keep in my personal folder, and it is a good illustration of when a skill earns its place - and when it does not.

Before: at the end of a session I would ask Claude "write me a PR description," and I would get something generic that leaned on commit messages and missed the why. After: with the skill, the instructions force it to read the actual diff and group by area, so the summary reflects what really changed, not what I labeled my commits. The output is consistent every time because the steps live in the skill instead of in my memory of how I phrased it last time.

What did not work at first: my initial description was just "summarize git changes," and Claude sometimes ignored it and answered from commit history instead. Adding the concrete trigger - "use when the user asks what changed or wants a PR summary" - fixed the auto-invocation. That is the honest lesson: a skill is only as good as its description, and you should expect to iterate on that one line a couple of times.

The other honest caveat: this is a small, task-shaped job, which is exactly what skills are for. If I had tried to encode my repo's entire coding style into a skill, that would be the wrong home - style that applies to every turn belongs in CLAUDE.md, not a skill that only loads on invoke.

Advanced: dynamic context & running a skill as a subagent

Two features make skills more powerful once you are comfortable with the basics.

Dynamic context injection. You can embed a shell command in your SKILL.md using the ` !`command` ` syntax, and Claude Code runs it and injects the output before Claude reads the skill body. That means the skill can act on live state instead of static text:

---
name: summarize-changes
description: Summarize the current git diff in plain English.
---

# Summarize changes

Here is the current diff:

!`git diff HEAD`

Summarize the changes above, grouped by area, in 3-6 bullets.

The ` !`git diff HEAD` ` line executes when the skill loads, so Claude sees the actual diff already inlined - no separate tool call needed.

Running a skill as a subagent. Set context: fork in the frontmatter and the skill runs in an isolated subagent with its own context window, returning only the result to your main session:

---
name: summarize-changes
description: Summarize the current git diff in an isolated subagent.
context: fork
---

This is ideal for token-heavy jobs - reviewing a huge diff, scanning many files - because the bulky intermediate work stays in the forked context and never clutters your main conversation. If you want to understand how forked skills relate to full subagents, that boundary is covered in the skills vs subagents vs hooks vs MCP comparison.

Don't build everything - prebuilt skill packs

Writing skills by hand is great when you want to tailor an exact workflow. But if you just want a solid library for common jobs - frontend, backend, database, DevOps, code review - you do not have to author every SKILL.md yourself. You can install a curated skill pack.

One popular option is AgentKit, a prebuilt skill pack for Claude Code (installed via its ak CLI) that ships 108+ ready-made skills. (AgentKit here means the kit for Claude Code - CLI ak, at agentkit.best - not OpenAI's AgentKit.) Its Engineer Kit is listed at $99 with lifetime updates and a money-back guarantee; the page does not state a recurring fee. If you would rather compare a few options first, my roundup of the best Claude Code kits in 2026 weighs them side by side. You can also browse the AgentKit skill pack (20% off via link) and judge for yourself.

Write your own skills first if your needs are small; a kit only pays off when you want to skip building a large library from scratch.

Best practices & limitations

Skills are handy, but they are not "install and it is perfect." Here is the honest picture:

• Descriptions are always in context. Every skill's one-line description sits in the context window at all times. That cost is tiny per skill, but installing dozens of overlapping skills adds up and can make it harder for Claude to pick the right one - keep names and descriptions distinct.
• The model can ignore a skill. If a skill does not auto-fire, the description is almost always too vague. Strengthen it with a concrete trigger ("use when…"), or just call it manually with /skill-name.
• An invoked skill persists across turns. Progressive disclosure saves tokens on the "not yet used" part, but once a skill loads, its body stays in context for the session. Keep bodies short and push long reference material into supporting files.
• Guard side-effecting actions. For skills that deploy, delete, or write to production, set disable-model-invocation so Claude cannot fire them on its own - you invoke them deliberately.
• Don't make everything a skill. Conventions that apply to every turn (your repo's general coding style) still belong in CLAUDE.md; skills are for per-task workflows. Choosing the right home is what keeps tokens efficient. You can also use the skill-creator tooling to evaluate a skill's pass-rate against its token cost before you commit to it.

FAQ

Are Claude Code skills free?

Yes - skills are a built-in feature of Claude Code, so using them and writing your own costs nothing beyond your existing Claude Code plan (for example, Pro at $20/month). A cost only appears if you choose to buy a third-party prebuilt skill pack.

Skills vs MCP - what's the difference?

A skill is markdown instructions (plus optional scripts) that shape how Claude does a task. MCP is a protocol that connects Claude to external tools and data. Skills change behavior; MCP adds capabilities. They work together - a skill can describe how to use an MCP-connected tool well.

Where do I put a skill?

Put personal skills in ~/.claude/skills/ (available everywhere on your machine) and project skills in .claude/skills/ inside a repo (commit it to share with your team). Each skill is its own folder containing a SKILL.md.

Can Claude invoke a skill automatically?

Yes. Claude matches your request against each skill's description and auto-invokes the best fit - you do not have to name it. You can also call one manually with /skill-name, or set disable-model-invocation to require manual invocation.

Do skills work in the Claude app and API too?

Yes. Skills follow the open Agent Skills standard, so they also work in the Claude apps (Pro, Max, Team, Enterprise) and via the Developer Platform / Skills API. Claude Code adds terminal-specific extras like invocation control, subagent execution, and dynamic context injection.

How is a skill different from CLAUDE.md?

CLAUDE.md holds conventions that apply to every turn and stays in context all the time. A skill holds instructions for a specific task and, thanks to progressive disclosure, only loads its full body when invoked. Use CLAUDE.md for always-on rules and skills for per-task workflows.

Conclusion & next steps

Claude Code skills are a clean way to teach Claude a job, one task at a time: a folder, a SKILL.md, fired automatically or with /skill-name, and kept cheap by progressive disclosure. From here, read the full skills vs subagents vs hooks vs MCP breakdown to place the whole family of concepts, revisit what Claude Code is if you are still getting oriented, and if you would rather start from a ready library than a blank file, try the AgentKit skill pack (20% off via link) before you write your own from scratch.