Claude Code Skills: The Practical Guide

What Claude Code skills are

Claude Code is Anthropic's agentic coding CLI — it also runs in the browser, a desktop app, VS Code, JetBrains, Slack, and CI/CD, but the terminal is the reference environment. A skill is a directory with a SKILL.md file: YAML frontmatter that tells Claude when to use it, plus markdown instructions Claude follows once it does. Type /skill-name to run one directly, or let Claude load it automatically when your request matches its description.

Claude Code skills follow the Agent Skills open standard, which Anthropic originally developed and which now works across Claude Code, Cursor, VS Code, Gemini CLI, and others. Claude Code is close to the reference implementation, and it extends the base spec with fields the standard doesn't define — invocation control, subagent execution, dynamic context injection. Which fields are portable and which are Claude-Code-only matters the moment you try to share a skill outside Claude Code, and it's the first thing this page covers.

Custom commands and skills are the same thing now. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work identically. Skills just add optional extras: a directory for supporting files, more frontmatter, and the ability for Claude to load them automatically.

Where skills live

Where you put a skill determines who can use it, and conflicts resolve in a fixed order:

When two skills share a name: enterprise overrides personal, and personal overrides project. A skill at any of those levels also overrides a bundled skill with the same name (but not the bundled skill's alias — a project code-review skill replaces /code-review, but typing the bundled alias /review still runs the original). Plugin skills are namespaced (/plugin-name:skill-name), so they never collide with anything else. A skill or command from any local source overrides a same-named skill synced from your claude.ai account.

Project skills also load from every .claude/skills/ between your starting directory and the repository root, and — separately — from nested .claude/skills/ directories below your starting directory the first time Claude touches a file there. A nested skill with the same name as one above it doesn't override; both stay available, with the nested one addressable as apps/web:deploy while the unqualified /deploy still runs the higher-level one (and Claude is told to also consider the nested variant when it's relevant).

Claude Code watches skill directories for changes and picks up edits within the session — no restart needed, unless you create a brand-new top-level skills directory that didn't exist when the session started.

The SKILL.md format, and what only works in Claude Code

my-skill/
├── SKILL.md           # required
├── template.md         # optional: for Claude to fill in
├── examples/
│   └── sample.md
└── scripts/
    └── validate.sh     # optional: Claude can execute this

Only SKILL.md is required. name and description are the only frontmatter fields most skills need — description is what Claude matches against your request, so put the key use case first.

Here's the split that matters if you plan to use a skill anywhere besides Claude Code. The full Claude Code frontmatter has about twenty optional fields. Package a skill for claude.ai uploads, the Skills API, or anthropics/skills' own package_skill.py, and only six of them are allowed:

Include a Claude-Code-only field when packaging for one of those portable paths, and validation fails outright with Unexpected key(s) in SKILL.md frontmatter, rather than silently dropping it. The reverse isn't a problem: every field in the left column plus every field in the right column works fine inside Claude Code itself — the restriction only bites when a skill leaves Claude Code.

The two frontmatter fields worth knowing by name:

• disable-model-invocation: true — only you can run it, with /name. Use for anything with side effects: /deploy, /commit, sending a message. Claude is explicitly blocked from working around this if it tries.
• user-invocable: false — only Claude can run it. Use for background knowledge — conventions, context — that isn't a meaningful action for a person to trigger by hand.

How skills are discovered and loaded

Skill descriptions load into context at session start so Claude knows what's available; full SKILL.md content loads only when a skill actually runs, and it stays in the conversation for the rest of the session — Claude doesn't re-read the file on later turns, so write instructions as standing guidance, not one-time steps.

If you have a lot of skills, the description listing itself has a budget: 1% of the model's context window by default. When it overflows, Claude Code drops descriptions starting with your least-used skills first. /doctor shows the listing's context cost; raise the budget with the skillListingBudgetFraction setting if you need to.

Auto-compaction carries invoked skills forward, but not indefinitely: after a summary, Claude Code re-attaches each skill's most recent invocation (up to 5,000 tokens each), sharing a combined 25,000-token budget across all of them — most-recently-invoked first. If a skill seems to stop influencing behavior after compaction, re-invoke it.

Skills you don't need to install

Claude Code ships with bundled skills in every session — they aren't installed from anywhere, and third-party "best skills" lists routinely fold them in as if they were: /code-review, /debug, /loop, /batch, /claude-api, /doctor, and the trio that launches and verifies your app — /run, /verify, and /run-skill-generator, which records a per-project launch recipe the first time it has to figure one out from scratch. Turn all of them off except /doctor with the disableBundledSkills setting.

Skills vs. commands vs. plugins vs. subagents vs. MCP

Five terms, five different jobs:

A skill with context: fork runs as a forked subagent in the background by default (set background: false to wait for it inline) — useful for research or review tasks that shouldn't crowd your main conversation. The built-in Explore and Plan agent types skip loading CLAUDE.md to keep their context small, so a forked skill using one of them sees only its own SKILL.md content and that agent's system prompt.

Dynamic context injection

A line starting with !`command` runs a shell command before the skill content reaches Claude, and the output replaces the placeholder — Claude sees real data, not the command that produced it:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`

## Your task
Summarize this pull request...

A failed command aborts the whole invocation — Claude never sees the skill for that run. With the default bash shell, append || true to any command you expect to sometimes exit non-zero. This never runs for a skill synced from your claude.ai account; those commands reach Claude as literal text instead, so a skill that depends on injected context behaves differently once synced.

Evaluating a skill with skill-creator

Anthropic's official skill-creator plugin (/plugin install skill-creator@claude-plugins-official) automates the only real way to know a skill works: a baseline comparison, run with the skill available and again with it disabled, on realistic prompts in a fresh session each time. It stores test cases in evals.json, runs each in an isolated subagent, grades output against your assertions, and rolls the results into a with-skill-vs-without-skill benchmark — plus a blind A/B between two versions of a skill, so you can confirm an edit actually helped before you commit it.

Common setup questions

Do commands and skills conflict? A file in .claude/commands/ and a skill with the same name both create the same slash command — the skill wins.

Where should I start looking for skills? See the best Claude Code skills for a shortlist verified against the actual repos, and Claude Code skills on GitHub for how to vet a repository yourself.

Is a skill scanned for anything dangerous before it runs? Not on its own — see how to install Claude Code skills for what actually gates a skill versus a plugin.

Limitations and caveats

• Frontmatter fields and version-gated behaviors here (for example, features requiring "Claude Code v2.1.145 or later") are current as of the docs snapshot in August 2026 and will drift as the CLI updates. Check the official skills docs if you're reading this much later.
• We have not run Claude Code or installed any of these skills ourselves. Behavior described here is documented behavior, not something we tested firsthand.
• The community-marketplace review pipeline's "automated validation and safety screening" is described only at a high level in the official docs; we have not independently verified how strict it is.

Sources

• Claude Code — Skills (official docs)
• Claude Code — Plugins
• Claude Code — Discover and install plugins
• anthropics/skills (GitHub) — official reference skills repo
• agentskills.io — the open standard Claude Code implements