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

For a head-to-head comparison of skills versus hooks, subagents, and plugins, see our extensibility decision guide.

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:

Skill	Purpose
/code-review	Review the current diff for correctness bugs and report findings
/batch	Execute multiple tasks in parallel across files in isolated worktrees
/debug	Investigate and diagnose issues from errors or logs
/loop	Run a task on a recurring interval within your session
/claude-api	Build, debug, and optimize Claude API / Anthropic SDK apps
/run	Launch and drive your app to see a change working
/verify	Build and run your app to confirm a code change does what it should
/run-skill-generator	Teach /run and /verify how to build and launch your project

/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:

For non-interactive use, skills also work with headless mode for fully scripted automation.

/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

---

Claude Code Skills: A Design Methodology

Designing Claude Code Skills well starts from the task the skill is meant to improve, not from the skill itself. The productive question is: what repeated reasoning does the model do that a skill could make faster, more reliable, or more consistent? Claude Code Skills that answer a real, recurring question compound value; skills that exist because the mechanism seemed interesting rarely justify their context cost. Naming the task before building the skill is the single discipline that separates useful skills from speculative ones.

The second design choice is scope. A skill that tries to cover an entire domain – “handle all security reviews” – is too broad to be reliably activated and too vague to be consistently good. A skill that covers a specific, well-bounded task – “review a pull request for SQL injection” – activates when it should and produces consistent results. Claude Code Skills with tight scope are the building blocks; broad skills are aspirations that never quite land.

The third choice is the description, because the description is what the model uses to decide whether to activate the skill. A description that names the trigger conditions precisely – when this skill applies, what it produces, what it does not cover – lets the model invoke it at the right moments and skip it at the wrong ones. Claude Code Skills with vague descriptions activate unpredictably, which undermines the consistency the skill was supposed to provide.

Skill Discovery and Activation

A skill only helps if it is discovered and activated at the right moment, and the discovery mechanism is what makes that reliable. The model sees the skill’s name and description in its available-skills list, and it decides whether to load the skill’s full content based on whether the current task matches. Claude Code Skills with precise descriptions are discovered accurately; ones with generic descriptions are either over-activated (loaded when not needed, wasting context) or under-activated (missed when needed, providing no benefit).

Activation carries a context cost – loading a skill’s full content into the session – so over-activation is a real problem, not just a cosmetic one. A skill that loads on every vaguely related task fills the context window with content the task did not need, which degrades reasoning on the actual question. Claude Code Skills that activate only on genuine matches keep the context lean, which is the same goal as careful context engineering elsewhere.

Tuning activation is an iterative process. After writing a skill, observe whether it activates on the tasks you expected and skips the ones you did not. If it over-activates, tighten the description to narrow the trigger; if it under-activates, broaden it or add synonyms for the task the user is likely to phrase. Claude Code Skills that are observed and tuned in real sessions converge on reliable activation; ones written and never revisited stay approximate.

Skill Composition

Complex tasks often need more than one skill, and composing skills – having the model activate several in sequence or in concert – is how Claude Code Skills scale to real workflows. A code review might draw on one skill for style, another for security, and a third for performance, each contributing its specialty to a combined assessment. Composition works when each skill has a clear boundary, so the model knows what each contributes and where one leaves off and another begins.

Composition rewards small, focused skills over large, overlapping ones. Two skills that cover related but distinct concerns compose cleanly; two skills that cover overlapping concerns compete, and the model’s choice between them becomes a source of inconsistency. Claude Code Skills designed for composition have non-overlapping remits, which lets the model combine them without having to resolve which one “wins” for a given subtask.

A skill can also compose with a subagent or a hook, each playing to its strength. The skill provides the structured approach; the subagent provides the isolated execution; the hook provides the enforced checkpoint. Claude Code Skills that are designed knowing they may be part of such a combination – documented for their specific role, not assuming they own the whole task – slot into larger architectures cleanly.

Testing and Iterating on Skills

A skill is a piece of prompt engineering, and like any prompt it benefits from testing. The most valuable test is a set of representative tasks with expected behaviors: for each, does the skill activate, and does it produce the kind of result the skill is meant to produce? Claude Code Skills tested against a fixture set catch the regressions that come from description edits, where a wording tweak that improved activation on one task quietly broke it on another.

Iteration is where skills get good. The first version of a skill is a hypothesis about what the model needs to know to do the task well; observation against real tasks tests the hypothesis, and revision updates it. Claude Code Skills that go through several observation-and-revision cycles converge on reliable quality; ones written once and shipped stay at the quality of the first guess, which is rarely good enough.

A common iteration finding is that a skill’s content is doing too much or too little. Too much – the skill loads a long, detailed procedure that the model follows rigidly even when the task does not need all of it – and the skill becomes a constraint rather than a help. Too little, and the skill adds nothing the model would not have done on its own. Claude Code Skills that hit the right depth – enough to steer, not so much to constrain – are the ones that earn their place.

Skill Performance and Context Cost

Every loaded skill adds to the session’s context, and the cost adds up. A session with many skills loaded has less room for the actual task’s content, which can degrade reasoning if the skills are not all relevant. Claude Code Skills that are lean – long enough to convey the approach, short enough to load cheaply – keep the context budget balanced; skills that are verbose load expensively and provide diminishing value per token.

The tradeoff between skill depth and context cost is real, and it favors brevity more than authors usually expect. A skill that is half the length but 90 percent as effective is usually the better choice, because the saved context improves every other interaction in the session. Claude Code Skills should be edited for density the way prose is edited for density: cut what does not carry weight, keep what does.

Conditional loading is the advanced lever for managing skill cost. A skill that exposes sub-sections, only some of which are relevant to a given task, can be structured so the model loads the relevant section rather than the whole. Claude Code Skills designed with this internal structure – a core that always loads, plus extensions that load on demand – scale to cover complex domains without paying the full context cost on every activation.

Skill Security Considerations

A skill’s content becomes part of the model’s reasoning, which means the skill is in the trust boundary. A skill that instructs the model to take an action is as powerful as a direct instruction from the user, so skills from untrusted sources are a prompt-injection vector. Claude Code Skills should come from reviewed sources, the same way plugins should, and their content should be readable before they are trusted to steer the model.

Skills that reference external resources – fetching a document, loading a config, pulling from an API – inherit the trust properties of those resources. A skill that loads a remote config is trusting that config not to contain adversarial instructions, which is a strong assumption about a remote resource. Claude Code Skills that keep their references local, or that treat fetched content strictly as data, are safer than ones that blend fetched content into the model’s instructions.

The action surface a skill enables should be proportionate to its purpose. A skill that helps the model format output does not need to enable destructive actions; a skill that guides a deployment does. Reviewing the action surface – what the skill, once loaded, makes the model more likely to do – is part of reviewing the skill itself, and Claude Code Skills that stay within their necessary action surface are safer neighbors in a session.

Team Skill Libraries

A skill library – a curated, reviewed collection that a team shares – is where Claude Code Skills deliver their largest payoff. Each skill in the library encodes a piece of the team’s expertise: how they review, how they triage, how they document, how they release. A teammate who draws on the library starts with the team’s accumulated approach rather than reinventing it, which is the difference between a coordinated team and a collection of individuals.

Library curation is itself a discipline. A library that grows without pruning accumulates overlapping, stale, or low-value skills that dilute the useful ones, because the model has to choose among more candidates at activation time. Claude Code Skills in a shared library should be periodically reviewed: still used, still accurate, still the best of the alternatives? Skills that fail these checks should be retired, and the library kept to a size where every entry earns its place.

Ownership matters for a shared library. Each skill should have a maintainer – someone responsible for keeping it accurate as the codebase and tools evolve, and for fielding reports when the skill misfires. Claude Code Skills without an owner decay silently; skills with an owner stay sharp, because someone is watching. Documenting ownership alongside the skill, in the library index, makes the responsibility visible and the maintenance accountable.

Skills Versus Subagents, Hooks, and Plugins

The four extension mechanisms – skills, subagents, hooks, and plugins – overlap in capability but differ in their best use, and choosing the right one is a recurring design decision. Claude Code Skills are best for encoding structured approaches the model should follow: they steer reasoning without isolating execution. Subagents are best for delegating self-contained tasks whose detail should not pollute the main context. Hooks are best for enforcing checkpoints that must run regardless of the model’s choices. Plugins are best for packaging and distributing a set of related capabilities.

The decision matters because the wrong mechanism produces a worse result than the right one. A task that needs isolated execution, put into a skill, ends up polluting the main context with detail a subagent would have contained. A checkpoint that must always run, put into a skill, gets skipped when the model decides the skill does not apply, where a hook would have enforced it. Claude Code Skills chosen for tasks that fit the skill mechanism are effective; chosen for tasks that fit another mechanism, they are a liability.

Many real workflows combine several mechanisms. A skill defines the approach, a subagent executes the heavy reading, a hook enforces the review step, and a plugin packages all three for distribution. Claude Code Skills fit naturally as the steering layer in such a combination, and skills designed with that role in mind – focused on how to think about the task, not on doing all the work themselves – compose with the other mechanisms cleanly.

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

Resource	Description
Official Skills Documentation	Complete skills reference from Anthropic
Agent Skills Architecture Blog	Deep dive into the skills architecture and design philosophy
Skills Repository (luongnv89/skills)	Collection of ready-to-use community skills including logo-designer and ollama-optimizer
Agent Skills Open Standard	The cross-tool standard that Claude Code skills follow
Agent Skill Manager (ASM)	Tool for skill development, duplicate detection, and testing

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.