Claude Code Skills Guide

Claude Code Skills — Building Claude Code skills lets you package reusable AI commands. Learn SKILL.md files, progressive disclosure, auto-invocation, and reference-file best practices.

Claude Code Skills: What You’ll Learn

In this guide to Claude Code Skills, you’ll work through practical, hands-on steps with real examples. Claude Code Skills is explained from the ground up so you can apply it immediately in your own projects.

Skills are reusable capabilities that Claude automatically discovers and uses based on context. They go beyond simple commands by supporting progressive loading to stay lightweight, dynamic shell context injection, subagent isolation, and fine-grained invocation control. This module walks through designing and building effective skills.

How Skills Load

Claude keeps skill loading efficient. Only skill descriptions are loaded upfront so Claude knows what’s available. The full SKILL.md content loads only when the skill is actually invoked, and supporting files are read on demand.

This means you can install many skills without flooding the context window. Claude learns they exist from their descriptions, then loads the actual instructions only for the skills it decides to use.

Skills live in .claude/skills/<name>/SKILL.md for project scope (committed to git) or ~/.claude/skills/<name>/SKILL.md for personal scope. Plugin skills use a plugin-name:skill-name namespace to avoid collisions with project or personal skills. When non-plugin skills share a name, the priority order is enterprise > personal > project.

Claude also auto-discovers skills from nested .claude/skills/ directories in subdirectories of the project root. For instance, if you’re working inside packages/frontend/, Claude will find skills defined in packages/frontend/.claude/skills/. This makes it easy to co-locate skills with specific packages or services in monorepo setups.

.claude/skills/code-review/
├── SKILL.md              # Instructions (required)
├── templates/
│   └── review-checklist.md
└── scripts/
    └── analyze-metrics.py

Writing Effective Skill Descriptions

The description field is arguably the most critical part of a skill. It controls when Claude auto-invokes the skill and must contain enough signal to match against real user requests. A vague description like “helps with code” will never trigger. A specific description with concrete trigger terms works:

---
name: security-review
description: Scan code for security vulnerabilities including injection flaws, authentication issues, and data exposure. Use when reviewing code changes, preparing a PR, or when the user mentions security, vulnerabilities, or audit.
---

Include the task type (“scan”, “generate”, “analyze”), the subject domain (“security”, “API”, “database”), and explicit trigger phrases (“when the user mentions”, “use when”). The skill listing truncates each entry’s combined description plus when_to_use text at 1,536 characters, so front-load the key use case and push overflow trigger phrases into when_to_use:

---
name: security-review
description: Scan code for security vulnerabilities including injection flaws, authentication issues, and data exposure.
when_to_use: When reviewing code changes, preparing a PR, or when the user mentions security, vulnerabilities, or audit.
---

Claude budgets total skill description space at roughly 1% of the model’s context window by default. Raise it with the skillListingBudgetFraction setting (e.g. 0.02 = 2%) or the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable for a fixed character count. Run /doctor to check whether the budget is overflowing and which skills are being dropped.

Supporting files extend the skill without inflating context. Reference them from SKILL.md with relative paths:

For the full review checklist, see [templates/review-checklist.md](templates/review-checklist.md).

Claude reads supporting files via bash when needed. Keep SKILL.md under 500 lines; put detailed reference material in separate files.

Dynamic Context and Invocation Control

The !command syntax executes shell commands before the skill content reaches Claude. The output is inlined — Claude only sees the result, not the command. This is how you give skills live context:

---
name: pr-summary
description: Summarize pull request changes. Use when asked to review or summarize a PR.
context: fork
agent: Explore
---

## PR context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

Summarize the intent and key changes in this pull request.

The shell field specifies which shell to use for !command blocks. Set it to powershell instead of the default bash when the PowerShell tool is enabled via CLAUDE_CODE_USE_POWERSHELL_TOOL=1. On Linux and macOS, enabling it also requires pwsh on your PATH:

---
name: windows-helper
description: Manage Windows services and configurations
shell: powershell
---

Two frontmatter fields control who can invoke a skill. disable-model-invocation: true means only the user can invoke it via /skill-name — Claude will never trigger it automatically. Use this for any skill with side effects (deploys, pushes, sends). user-invocable: false hides the skill from the / menu while still letting Claude auto-invoke it — ideal for background knowledge skills that aren’t actionable as commands.

paths: accepts a YAML list of globs that scope when a skill applies. When set, the skill only loads when the working directory matches one of the globs. This keeps project-specific skills from leaking into unrelated sessions:

---
name: api-generator
description: Generate REST API endpoints from schema definitions.
paths: ["src/**/*.ts", "tests/**"]
---

effort controls reasoning depth for the skill. Values are low, medium, high, xhigh, and max (session-only). Use low for quick lookups or boilerplate generation, medium for most tasks, and high for deep analysis requiring careful reasoning:

---
name: security-review
description: Scan code for security vulnerabilities.
effort: high
---

context: fork runs the skill in an isolated subagent with its own context window. The agent field specifies which agent type: Explore for read-only research, Plan for planning, general-purpose for anything needing all tools. The main conversation stays clean while the subagent does the heavy lifting.

The model field specifies which model to use when the skill is active. This is useful when a task benefits from a specific model’s strengths (e.g., opus for complex reasoning, sonnet for fast execution):

---
name: deep-analysis
description: Thoroughly analyze the codebase for a specific pattern or issue
context: fork
agent: Explore
model: opus
disable-model-invocation: true
---

Analyze $ARGUMENTS across the entire codebase:
1. Use Glob and Grep to find all occurrences
2. Read each file and understand context
3. Summarize patterns, inconsistencies, and recommendations

Arguments and Tool Access

Skills accept arguments in two ways. $ARGUMENTS captures everything after the command name as a single string. $0, $1, $2 capture individual space-separated arguments. You can also declare named arguments with the arguments frontmatter field — names map to positions, so $issue expands to the first argument and $branch to the second. All substitutions happen before the prompt reaches Claude. argument-hint improves slash-menu autocomplete by showing what arguments a skill expects:

---
name: review-pr
description: Review a GitHub PR by number
argument-hint: "<pr-number> <priority>"
allowed-tools: Bash(gh *), Read, Grep, Glob
---

Review PR #$0 with priority $1. Focus on security and performance.

Reference our standards in [standards/code-review.md](standards/code-review.md).

Usage: /review-pr 456 high — $0 becomes 456, $1 becomes high.

allowed-tools grants permission for the listed tools while the skill is active — it does not restrict which tools are available. Your permission settings still govern unlisted tools.

Beyond positional arguments, skills support built-in substitution variables: ${CLAUDE_SESSION_ID} for the current session ID (useful for logging), ${CLAUDE_EFFORT} for the active effort level, and ${CLAUDE_SKILL_DIR} for the directory containing the skill’s SKILL.md file (use it to reference bundled scripts regardless of working directory).

Legacy command files in .claude/commands/*.md still work, but skills are the recommended format. If both exist with the same name, the skill takes priority.

Skill Visibility Overrides

The skillOverrides setting in settings.json controls skill visibility without editing the skill’s own frontmatter. This is useful for shared project skills or plugin-provided skills you can’t modify. The /skills menu lets you cycle states interactively — highlight a skill, press Space to cycle, then Enter to save to .claude/settings.local.json:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Values: "on" (default — full listing), "name-only" (name visible but description hidden), "user-invocable-only" (hidden from Claude but in / menu), "off" (hidden everywhere).

Built-in Skills

Claude Code ships with a set of bundled skills available in every session, including /code-review, /batch, /debug, /loop, and /claude-api. Three additional bundled skills — /run, /verify, and /run-skill-generator — require v2.1.145+ and work together to launch your app and confirm changes against the running app instead of just tests:

/run and /verify infer the launch from your project type (CLI, server, TUI, browser-driven) and from package.json, Makefile, or your README. For projects that need anything beyond a standard launch — a database, an env file, a multi-step build — run /run-skill-generator once. It gets your app running from a clean environment, captures what worked, and commits it as a per-project skill at .claude/skills/run-<name>/. After that, /run and /verify follow the recorded recipe instead of guessing.

/fewer-permission-prompts scans your conversation transcripts for common read-only Bash and MCP tool calls, then proposes a prioritized allowlist for your .claude/settings.json. Run it after a few sessions to generate a permission configuration tailored to your actual workflow:

/fewer-permission-prompts

Real-World Skill Examples

Example 1: Brand Voice Consistency Skill

This skill ensures all communications maintain consistent brand voice:

---
name: brand-voice-consistency
description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, public-facing content, or when users mention brand voice, tone, or writing style.
---

# Brand Voice Skill

## Tone of Voice
- Friendly but professional — approachable without being casual
- Clear and concise — avoid jargon, explain technical concepts simply
- Confident — we know what we're doing

## Writing Guidelines
### Do's ✅
- Use "you" when addressing readers
- Use active voice: "Claude generates reports" not "Reports are generated"
- Start with value proposition

### Don'ts ❌
- Don't use corporate jargon ("leverage", "synergize", "paradigm shift")
- Don't patronize or oversimplify

Example 2: Code Review Specialist Skill

A comprehensive code review skill with reference files:

---
name: code-review-specialist
description: Comprehensive code review with security, performance, and quality analysis. Use when users ask to review code, analyze code quality, or evaluate pull requests.
---

# Code Review Skill

Focus areas:
1. **Security Analysis** — injection vulnerabilities, data exposure risks
2. **Performance Review** — algorithm efficiency, memory optimization
3. **Code Quality** — SOLID principles, design patterns
4. **Maintainability** — readability, cyclomatic complexity

## Reference Files
- templates/review-checklist.md — Structured review checklist
- templates/finding-template.md — Standard finding documentation format
- scripts/analyze-metrics.py — Code metrics calculator

Example 3: API Documentation Generator Skill

---
name: api-documentation-generator
description: Generate comprehensive API documentation from source code. Use when creating or updating API documentation or generating OpenAPI specs.
---

# API Documentation Generator

Generates:
- OpenAPI/Swagger specifications
- API endpoint documentation
- SDK usage examples
- Error code references

Pro Tips

• Make descriptions specific with trigger terms — “Helps with documents” is useless. “Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction” enables auto-invocation.
• Keep SKILL.md under 500 lines — move detailed reference material, large examples, and specifications to separate files that load at Level 3 (as needed). This minimizes context usage.
• One skill equals one capability — “PDF form filling” is a good skill. “Document processing” is too broad and will trigger on unrelated requests or miss relevant ones.
• Use context: fork for heavy analysis tasks — running a skill in a subagent keeps the main conversation uncluttered. Use agent: Explore for read-only research or agent: general-purpose for tasks needing all tools.
• Audit skills from untrusted sources thoroughly — a malicious skill can direct Claude to invoke tools or execute code in harmful ways. Treat installing a skill like installing software.

Hands-On Challenge

Build a complete, production-ready skill that demonstrates progressive disclosure.

Task: Create a Code Review Specialist Skill

Design a skill that performs comprehensive code reviews with security, performance, and quality analysis using supporting files for progressive disclosure.

Steps

1. Create the skill directory structure: .claude/skills/code-review-specialist/ with subdirectories templates/ and references/.
2. Write SKILL.md with a specific description containing trigger keywords like “review code”, “analyze code quality”, “security analysis”, “pull request”.
3. Create a templates/review-checklist.md with categorized checks (security, performance, SOLID principles, naming conventions).
4. Create a references/finding-template.md showing the expected output format for each finding (Issue, Location, Impact, Severity, Fix).
5. Keep SKILL.md under 500 lines — move detailed checklists to the supporting files.
6. Reference supporting files from SKILL.md using relative paths like [review checklist](templates/review-checklist.md).
7. Test auto-invocation by asking Claude “Can you review this code for security issues?” without explicitly calling the skill.

Expected Outcome

When you ask Claude to review code, the skill auto-activates based on the description keywords. Claude loads the instructions from SKILL.md, then pulls in the checklist template as needed. The review output follows your structured finding format with categorized severity levels.

Hint

Front-load your trigger keywords in the description field — this is what Claude matches against. Use user-invocable: false if you want the skill to be invisible in the slash menu but still auto-activated. Check the code-review-specialist and refactor examples in the skills guide.

Knowledge Check

Test your understanding of Claude Code skills with these questions:

1. What are the 3 levels of progressive disclosure in the skill system?
   A) Metadata, instructions, resources | B) Name, body, attachments | C) Header, content, scripts | D) Summary, details, data
   Answer: A — Level 1: Metadata (~100 tokens, always loaded), Level 2: SKILL.md body (<5k tokens, loaded on trigger), Level 3: Bundled resources (scripts/references/assets, loaded on demand).
2. What is the most important factor for a skill to be auto-invoked by Claude?
   A) The skill’s file name | B) The description field in frontmatter with when-to-use keywords | C) The skill’s directory location | D) The auto-invoke: true frontmatter field
   Answer: B — Claude decides whether to auto-invoke a skill based solely on its description field. It must include specific trigger phrases and scenarios.
3. What is the maximum recommended length for a SKILL.md file?
   A) 100 lines | B) 250 lines | C) 500 lines | D) 1000 lines
   Answer: C — SKILL.md should be kept under 500 lines. Larger reference material belongs in references/ subdirectory files.
4. How do you make a skill run in an isolated subagent with its own context?
   A) Set isolation: true in frontmatter | B) Set context: fork with an agent field in frontmatter | C) Set subagent: true in frontmatter | D) Put the skill in .claude/agents/
   Answer: B — context: fork runs the skill in a separate context, and the agent field specifies which agent type to use.
5. A skill needs to reference a large API specification. Where should you put it?
   A) Inline in SKILL.md | B) In a references/api-spec.md file inside the skill directory | C) In the project’s CLAUDE.md | D) In a separate .claude/rules/ file
   Answer: B — Large reference material belongs in the references/ subdirectory. Claude loads Level 3 resources on demand, keeping SKILL.md lean.

Additional Resources

Claude Code Skills gives you a solid, repeatable workflow. Bookmark this Claude Code Skills guide and revisit the steps whenever you need them.

A Worked Example: Building a Code Review Specialist Skill

The clearest way to see how Claude Code Skills fit together is to build one end to end. Here’s a walkthrough for a skill that reviews pull requests against a team’s house style.

1. Create the directory. Skills live at .claude/skills/<name>/SKILL.md for project scope (checked into the repo, shared with the team) or ~/.claude/skills/ for personal scope (available across every project on your machine). For a code review skill tied to one repo’s conventions, project scope is the right call:

mkdir -p .claude/skills/code-review-specialist/templates
mkdir -p .claude/skills/code-review-specialist/references
touch .claude/skills/code-review-specialist/SKILL.md

2. Write a description with real trigger terms. The description field is the only thing Claude scans before deciding whether to load the skill, so it has to name the situations that should invoke it — not just describe what the skill does in the abstract:

---
name: code-review-specialist
description: Reviews pull requests and diffs for our house style — naming conventions, error handling patterns, and test coverage gaps. Use when the user asks to review a PR, check a diff, or "look over" recent changes before merging.
when_to_use: Before merging a PR, after implementing a feature, or when asked for a second opinion on a diff.
---

3. Keep SKILL.md itself short. The body should stay well under 500 lines — it’s meant to hold the core review checklist and workflow, not every edge case. Anything longer belongs in a supporting file that’s pulled in only when needed (progressive disclosure again, at the file level this time). Reference it with a relative markdown link so Claude follows it on demand:

See [naming conventions](references/naming.md) for full detail on variable and function naming.
Use [the review comment template](templates/comment.md) when leaving inline feedback.

4. Test auto-invocation, not the skill directly. Don’t open the skill and run it manually — that only proves the instructions work, not that Claude Code Skills will find it. Instead, ask a natural question in a fresh session, like “can you review the changes on this branch before I open a PR?”, and confirm the skill fires without being named. If it doesn’t, the description is too vague or missing the phrasing people actually use.
5. Consider isolating heavier variants. A lightweight review (a few files, a quick pass) can run inline. But a full-repo audit that reads dozens of files and produces a long report can pollute the main conversation’s context. For that variant, add context: fork plus an agent field pointing at a general-purpose explorer:

---
name: code-review-full-audit
description: Runs a full repository code review audit across all changed files with detailed findings.
context: fork
agent: Explore
---

The forked run does its reading and analysis in an isolated context, then reports back a summary — the main conversation only sees the result, not every file it opened along the way. That single design decision — inline for quick checks, forked for heavy ones — is usually the difference between a skill that’s pleasant to use and one that floods the transcript.

Claude Code Skills: Common Mistakes to Avoid

Most problems with Claude Code Skills trace back to a handful of avoidable setup mistakes.

• Vague descriptions with no trigger terms. A description like “helps with code” gives Claude nothing to match against, so the skill almost never auto-invokes — write descriptions around the specific phrases and situations a user would actually type.
• Letting SKILL.md balloon past 500 lines. Cramming every edge case into the main file defeats progressive disclosure and wastes context on every load — push detail into references/ files and link to them instead.
• Skipping disable-model-invocation on skills with side effects. A skill that deploys, pushes, or deletes something should never fire just because a description loosely matched the conversation — set disable-model-invocation: true so it only runs when explicitly invoked, rather than relying on user-invocable: false alone, which controls a different axis of who can trigger it.
• Building one oversized “do everything” skill. A skill that tries to handle linting, testing, review, and deployment in one SKILL.md ends up with a description too broad to trigger reliably on any single task — several small, single-purpose skills compose and auto-invoke far better than one catch-all.

Claude Code Skills: Best Practices

• Write one SKILL.md per skill with a tight description so auto-invocation triggers correctly.
• Use progressive disclosure: keep the main file short and link reference files for detail.
• Test the trigger phrasing so the skill activates exactly when intended and not otherwise.
• Keep skills single-purpose; compose several small skills rather than one giant one.
• Version and document skills so your team can reuse and improve them.

Claude Code Skills: Frequently Asked Questions

What are the actual loading stages behind progressive disclosure?

Three levels: skill metadata (name and description) is always loaded so Claude can scan for a match; the SKILL.md body loads only once a trigger fires; and bundled resources like reference files or templates load only when the skill body links to them and Claude follows the link.

When should a skill use context: fork instead of running inline?

Use context: fork with an agent field when the skill does heavy, multi-file work that would otherwise flood the main conversation’s context — the forked run does its reading in isolation and reports back a summary, keeping the parent thread clean.

What’s the difference between disable-model-invocation and user-invocable: false?

disable-model-invocation: true stops Claude from auto-triggering the skill based on the description — useful for skills with side effects — while user-invocable: false hides the skill from manual/slash invocation by a person, controlling a different axis of access.

If a skill and a legacy custom command share a name, which one wins?

Claude Code Skills take priority over legacy custom commands with the same trigger phrasing, since skills are the newer, more structured mechanism — keep names distinct to avoid ambiguity in which one actually runs.

What does the paths: field do?

paths: scopes a skill to specific glob patterns so it only becomes eligible for auto-invocation when the active files or working directory match — handy for skills tied to a particular subproject or file type rather than the whole repo.