1# Agent Skills1# Extend Claude with skills
2 2
3> Create, manage, and share Skills to extend Claude's capabilities in Claude Code.3> Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom slash commands.
4 4
5This guide shows you how to create, use, and manage Agent Skills in Claude Code. For background on how Skills work across Claude products, see [What are Skills?](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).5Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`.
6 6
7A Skill is a markdown file that teaches Claude how to do something specific: reviewing PRs using your team's standards, generating commit messages in your preferred format, or querying your company's database schema. When you ask Claude something that matches a Skill's purpose, Claude automatically applies it.7<Note>
8 For built-in commands like `/help` and `/compact`, see [interactive mode](/en/interactive-mode#built-in-commands).
8 9
9## Create your first Skill10 **Custom slash commands have been merged into skills.** A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Your existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to [control whether you or Claude invokes them](#control-who-invokes-a-skill), and the ability for Claude to load them automatically when relevant.
11</Note>
10 12
11This example creates a personal Skill that teaches Claude to explain code using visual diagrams and analogies. Unlike Claude's default explanations, this Skill ensures every explanation includes an ASCII diagram and a real-world analogy.13Claude Code skills follow the [Agent Skills](https://agentskills.io) open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like [invocation control](#control-who-invokes-a-skill), [subagent execution](#run-skills-in-a-subagent), and [dynamic context injection](#inject-dynamic-context).
12 14
13<Steps>15## Getting started
14 <Step title="Check available Skills">
15 Before creating a Skill, see what Skills Claude already has access to:
16 16
17 ```17### Create your first skill
18 What Skills are available?
19 ```
20 18
21 Claude will list any Skills currently loaded. You may see none, or you may see Skills from plugins or your organization.19This example creates a skill that teaches Claude to explain code using visual diagrams and analogies. Since it uses default frontmatter, Claude can load it automatically when you ask how something works, or you can invoke it directly with `/explain-code`.
22 </Step>
23 20
24 <Step title="Create the Skill directory">21<Steps>
25 Create a directory for the Skill in your personal Skills folder. Personal Skills are available across all your projects. (You can also create [project Skills](#where-skills-live) in `.claude/skills/` to share with your team.)22 <Step title="Create the skill directory">
23 Create a directory for the skill in your personal skills folder. Personal skills are available across all your projects.
26 24
27 ```bash theme={null}25 ```bash theme={null}
28 mkdir -p ~/.claude/skills/explaining-code26 mkdir -p ~/.claude/skills/explain-code
29 ```27 ```
30 </Step>28 </Step>
31 29
32 <Step title="Write SKILL.md">30 <Step title="Write SKILL.md">
33 Every Skill needs a `SKILL.md` file. The file starts with YAML metadata between `---` markers and must include a `name` and `description`, followed by Markdown instructions that Claude follows when the Skill is active.31 Every skill needs a `SKILL.md` file with two parts: YAML frontmatter (between `---` markers) that tells Claude when to use the skill, and markdown content with instructions Claude follows when the skill is invoked. The `name` field becomes the `/slash-command`, and the `description` helps Claude decide when to load it automatically.
34
35 The `description` is especially important, because Claude uses it to decide when to apply the Skill.
36 32
37 Create `~/.claude/skills/explaining-code/SKILL.md`:33 Create `~/.claude/skills/explain-code/SKILL.md`:
38 34
39 ```yaml theme={null}35 ```yaml theme={null}
40 ---36 ---
41 name: explaining-code37 name: explain-code
42 description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"38 description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
43 ---39 ---
44 40
53 ```49 ```
54 </Step>50 </Step>
55 51
56 <Step title="Load and verify the Skill">52 <Step title="Test the skill">
57 Exit and restart Claude Code to load the new Skill. Then verify it appears in the list:53 You can test it two ways:
54
55 **Let Claude invoke it automatically** by asking something that matches the description:
58 56
59 ```57 ```
60 What Skills are available?58 How does this code work?
61 ```59 ```
62 60
63 You should see `explaining-code` in the list with its description.61 **Or invoke it directly** with the skill name:
64 </Step>
65
66 <Step title="Test the Skill">
67 Open any file in your project and ask Claude a question that matches the Skill's description:
68 62
69 ```63 ```
70 How does this code work?64 /explain-code src/auth/login.ts
71 ```65 ```
72 66
73 Claude should ask to use the `explaining-code` Skill, then include an analogy and ASCII diagram in its explanation. If the Skill doesn't trigger, try rephrasing to include more keywords from the description, like "explain how this works."67 Either way, Claude should include an analogy and ASCII diagram in its explanation.
74 </Step>68 </Step>
75</Steps>69</Steps>
76 70
77The rest of this guide covers how Skills work, configuration options, and troubleshooting.71### Where skills live
78 72
79## How Skills work73Where you store a skill determines who can use it:
80 74
81Skills are **model-invoked**: Claude decides which Skills to use based on your request. You don't need to explicitly call a Skill. Claude automatically applies relevant Skills when your request matches their description.75| Location | Path | Applies to |
76| :--------- | :----------------------------------------------- | :----------------------------- |
77| Enterprise | See [managed settings](/en/iam#managed-settings) | All users in your organization |
78| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All your projects |
79| Project | `.claude/skills/<skill-name>/SKILL.md` | This project only |
80| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Where plugin is enabled |
82 81
83When you send a request, Claude follows these steps to find and use relevant Skills:82Project skills override personal skills with the same name. If you have files in `.claude/commands/`, those work the same way but a skill takes precedence over a command with the same name.
84 83
85<Steps>84#### Automatic discovery from nested directories
86 <Step title="Discovery">
87 At startup, Claude loads only the name and description of each available Skill. This keeps startup fast while giving Claude enough context to know when each Skill might be relevant.
88 </Step>
89 85
90 <Step title="Activation">86When you work with files in subdirectories, Claude Code automatically discovers skills from nested `.claude/skills/` directories. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills.
91 When your request matches a Skill's description, Claude asks to use the Skill. You'll see a confirmation prompt before the full `SKILL.md` is loaded into context. Since Claude reads these descriptions to find relevant Skills, [write descriptions](#skill-not-triggering) that include keywords users would naturally say.
92 </Step>
93 87
94 <Step title="Execution">88Each skill is a directory with `SKILL.md` as the entrypoint:
95 Claude follows the Skill's instructions, loading referenced files or running bundled scripts as needed.89
96 </Step>90```
97</Steps>91my-skill/
92├── SKILL.md # Main instructions (required)
93├── template.md # Template for Claude to fill in
94├── examples/
95│ └── sample.md # Example output showing expected format
96└── scripts/
97 └── validate.sh # Script Claude can execute
98```
98 99
99### Where Skills live100The `SKILL.md` contains the main instructions and is required. Other files are optional and let you build more powerful skills: templates for Claude to fill in, example outputs showing the expected format, scripts Claude can execute, or detailed reference documentation. Reference these files from your `SKILL.md` so Claude knows what they contain and when to load them. See [Add supporting files](#add-supporting-files) for more details.
100 101
101Where you store a Skill determines who can use it:102<Note>
103 Files in `.claude/commands/` still work and support the same [frontmatter](#frontmatter-reference). Skills are recommended since they support additional features like supporting files.
104</Note>
102 105
103| Location | Path | Applies to |106## Configure skills
104| :--------- | :---------------------------------------------------------- | :-------------------------------- |107
105| Enterprise | See [managed settings](/en/iam#enterprise-managed-settings) | All users in your organization |108Skills are configured through YAML frontmatter at the top of `SKILL.md` and the markdown content that follows.
106| Personal | `~/.claude/skills/` | You, across all projects |
107| Project | `.claude/skills/` | Anyone working in this repository |
108| Plugin | Bundled with [plugins](/en/plugins) | Anyone with the plugin installed |
109 109
110If two Skills have the same name, the higher row wins: enterprise overrides personal, personal overrides project, and project overrides plugin.110### Types of skill content
111 111
112### When to use Skills versus other options112Skill files can contain any instructions, but thinking about how you want to invoke them helps guide what to include:
113 113
114Claude Code offers several ways to customize behavior. The key difference: **Skills are triggered automatically by Claude** based on your request, while slash commands require you to type `/command` explicitly.114**Reference content** adds knowledge Claude applies to your current work. Conventions, patterns, style guides, domain knowledge. This content runs inline so Claude can use it alongside your conversation context.
115 115
116| Use this | When you want to... | When it runs |116```yaml theme={null}
117| :--------------------------------------- | :------------------------------------------------------------------------- | :----------------------------------------- |117---
118| **Skills** | Give Claude specialized knowledge (e.g., "review PRs using our standards") | Claude chooses when relevant |118name: api-conventions
119| **[Slash commands](/en/slash-commands)** | Create reusable prompts (e.g., `/deploy staging`) | You type `/command` to run it |119description: API design patterns for this codebase
120| **[CLAUDE.md](/en/memory)** | Set project-wide instructions (e.g., "use TypeScript strict mode") | Loaded into every conversation |120---
121| **[Subagents](/en/sub-agents)** | Delegate tasks to a separate context with its own tools | Claude delegates, or you invoke explicitly |
122| **[Hooks](/en/hooks)** | Run scripts on events (e.g., lint on file save) | Fires on specific tool events |
123| **[MCP servers](/en/mcp)** | Connect Claude to external tools and data sources | Claude calls MCP tools as needed |
124 121
125**Skills vs. subagents**: Skills add knowledge to the current conversation. Subagents run in a separate context with their own tools. Use Skills for guidance and standards; use subagents when you need isolation or different tool access.122When writing API endpoints:
123- Use RESTful naming conventions
124- Return consistent error formats
125- Include request validation
126```
126 127
127**Skills vs. MCP**: Skills tell Claude *how* to use tools; MCP *provides* the tools. For example, an MCP server connects Claude to your database, while a Skill teaches Claude your data model and query patterns.128**Task content** gives Claude step-by-step instructions for a specific action, like deployments, commits, or code generation. These are often actions you want to invoke directly with `/skill-name` rather than letting Claude decide when to run them. Add `disable-model-invocation: true` to prevent Claude from triggering it automatically.
128 129
129<Note>130```yaml theme={null}
130 For a deep dive into the architecture and real-world applications of Agent Skills, read [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).131---
131</Note>132name: deploy
133description: Deploy the application to production
134context: fork
135disable-model-invocation: true
136---
132 137
133## Configure Skills138Deploy the application:
1391. Run the test suite
1402. Build the application
1413. Push to the deployment target
142```
134 143
135This section covers Skill file structure, supporting files, tool restrictions, and distribution options.144Your `SKILL.md` can contain anything, but thinking through how you want the skill invoked (by you, by Claude, or both) and where you want it to run (inline or in a subagent) helps guide what to include. For complex skills, you can also [add supporting files](#add-supporting-files) to keep the main skill focused.
136 145
137### Write SKILL.md146### Frontmatter reference
138 147
139The `SKILL.md` file is the only required file in a Skill. It has two parts: YAML metadata (the section between `---` markers) at the top, and Markdown instructions that tell Claude how to use the Skill:148Beyond the markdown content, you can configure skill behavior using YAML frontmatter fields between `---` markers at the top of your `SKILL.md` file:
140 149
141```yaml theme={null}150```yaml theme={null}
142---151---
143name: your-skill-name152name: my-skill
144description: Brief description of what this Skill does and when to use it153description: What this skill does
154disable-model-invocation: true
155allowed-tools: Read, Grep
145---156---
146 157
147# Your Skill Name158Your skill instructions here...
148
149## Instructions
150Provide clear, step-by-step guidance for Claude.
151
152## Examples
153Show concrete examples of using this Skill.
154```159```
155 160
156#### Available metadata fields161All fields are optional. Only `description` is recommended so Claude knows when to use the skill.
157
158You can use the following fields in the YAML frontmatter:
159 162
160| Field | Required | Description |163| Field | Required | Description |
161| :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |164| :------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
162| `name` | Yes | Skill name. Must use lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |165| `name` | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |
163| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |166| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. |
164| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. See [Restrict tool access](#restrict-tool-access-with-allowed-tools). |167| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |
165| `model` | No | [Model](https://docs.claude.com/en/docs/about-claude/models/overview) to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |168| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. |
169| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |
170| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. |
171| `model` | No | Model to use when this skill is active. |
172| `context` | No | Set to `fork` to run in a forked subagent context. |
173| `agent` | No | Which subagent type to use when `context: fork` is set. |
174| `hooks` | No | Hooks scoped to this skill's lifecycle. See [Hooks](/en/hooks) for configuration format. |
166 175
167See the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance including validation rules.176#### Available string substitutions
168 177
169### Update or delete a Skill178Skills support string substitution for dynamic values in the skill content:
170 179
171To update a Skill, edit its `SKILL.md` file directly. To remove a Skill, delete its directory. Exit and restart Claude Code for changes to take effect.180| Variable | Description |
181| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
182| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |
183| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |
172 184
173### Add supporting files with progressive disclosure185**Example using substitutions:**
174 186
175Skills share Claude's context window with conversation history, other Skills, and your request. To keep context focused, use **progressive disclosure**: put essential information in `SKILL.md` and detailed reference material in separate files that Claude reads only when needed.187```yaml theme={null}
188---
189name: session-logger
190description: Log activity for this session
191---
176 192
177This approach lets you bundle comprehensive documentation, examples, and scripts without consuming context upfront. Claude loads additional files only when the task requires them.193Log the following to logs/${CLAUDE_SESSION_ID}.log:
178 194
179<Tip>Keep `SKILL.md` under 500 lines for optimal performance. If your content exceeds this, split detailed reference material into separate files.</Tip>195$ARGUMENTS
196```
180 197
181#### Example: multi-file Skill structure198### Add supporting files
182 199
183Claude discovers supporting files through links in your `SKILL.md`. The following example shows a Skill with detailed documentation in separate files and utility scripts that Claude can execute without reading:200Skills can include multiple files in their directory. This keeps `SKILL.md` focused on the essentials while letting Claude access detailed reference material only when needed. Large reference docs, API specifications, or example collections don't need to load into context every time the skill runs.
184 201
185```202```
186my-skill/203my-skill/
191 └── helper.py (utility script - executed, not loaded)208 └── helper.py (utility script - executed, not loaded)
192```209```
193 210
194The `SKILL.md` file references these supporting files so Claude knows they exist:211Reference supporting files from `SKILL.md` so Claude knows what each file contains and when to load it:
195
196````markdown theme={null}
197## Overview
198
199[Essential instructions here]
200 212
213```markdown theme={null}
201## Additional resources214## Additional resources
202 215
203- For complete API details, see [reference.md](reference.md)216- For complete API details, see [reference.md](reference.md)
204- For usage examples, see [examples.md](examples.md)217- For usage examples, see [examples.md](examples.md)
218```
205 219
206## Utility scripts220<Tip>Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files.</Tip>
207 221
208To validate input files, run the helper script. It checks for required fields and returns any validation errors:222### Control who invokes a skill
209```bash
210python scripts/helper.py input.txt
211```
212````
213 223
214<Tip>Keep references one level deep. Link directly from `SKILL.md` to reference files. Deeply nested references (file A links to file B which links to file C) may result in Claude partially reading files.</Tip>224By default, both you and Claude can invoke any skill. You can type `/skill-name` to invoke it directly, and Claude can load it automatically when relevant to your conversation. Two frontmatter fields let you restrict this:
215 225
216**Bundle utility scripts for zero-context execution.** Scripts in your Skill directory can be executed without loading their contents into context. Claude runs the script and only the output consumes tokens. This is useful for:226* **`disable-model-invocation: true`**: Only you can invoke the skill. Use this for workflows with side effects or that you want to control timing, like `/commit`, `/deploy`, or `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.
217 227
218* Complex validation logic that would be verbose to describe in prose228* **`user-invocable: false`**: Only Claude can invoke the skill. Use this for background knowledge that isn't actionable as a command. A `legacy-system-context` skill explains how an old system works. Claude should know this when relevant, but `/legacy-system-context` isn't a meaningful action for users to take.
219* Data processing that's more reliable as tested code than generated code
220* Operations that benefit from consistency across uses
221 229
222In `SKILL.md`, tell Claude to run the script rather than read it:230This example creates a deploy skill that only you can trigger. The `disable-model-invocation: true` field prevents Claude from running it automatically:
223 231
224```markdown theme={null}232```yaml theme={null}
225Run the validation script to check the form:233---
226python scripts/validate_form.py input.pdf234name: deploy
235description: Deploy the application to production
236disable-model-invocation: true
237---
238
239Deploy $ARGUMENTS to production:
240
2411. Run the test suite
2422. Build the application
2433. Push to the deployment target
2444. Verify the deployment succeeded
227```245```
228 246
229For complete guidance on structuring Skills, see the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns).247Here's how the two fields affect invocation and context loading:
230 248
231### Restrict tool access with allowed-tools249| Frontmatter | You can invoke | Claude can invoke | When loaded into context |
250| :------------------------------- | :------------- | :---------------- | :----------------------------------------------------------- |
251| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
252| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |
253| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |
232 254
233Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active:255<Note>
256 In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked. [Subagents with preloaded skills](/en/sub-agents#preload-skills-into-subagents) work differently: the full skill content is injected at startup.
257</Note>
258
259### Restrict tool access
260
261Use the `allowed-tools` field to limit which tools Claude can use when a skill is active. This skill creates a read-only mode where Claude can explore files but not modify them:
234 262
235```yaml theme={null}263```yaml theme={null}
236---264---
237name: reading-files-safely265name: safe-reader
238description: Read files without making changes. Use when you need read-only file access.266description: Read files without making changes
239allowed-tools: Read, Grep, Glob267allowed-tools: Read, Grep, Glob
240---268---
269```
270
271### Pass arguments to skills
241 272
242# Safe File Reader273Both you and Claude can pass arguments when invoking a skill. Arguments are available via the `$ARGUMENTS` placeholder.
243 274
244This Skill provides read-only file access.275This skill fixes a GitHub issue by number. The `$ARGUMENTS` placeholder gets replaced with whatever follows the skill name:
245 276
246## Instructions277```yaml theme={null}
2471. Use Read to view file contents278---
2482. Use Grep to search within files279name: fix-issue
2493. Use Glob to find files by pattern280description: Fix a GitHub issue
281disable-model-invocation: true
282---
283
284Fix GitHub issue $ARGUMENTS following our coding standards.
285
2861. Read the issue description
2872. Understand the requirements
2883. Implement the fix
2894. Write tests
2905. Create a commit
250```291```
251 292
252When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:293When you run `/fix-issue 123`, Claude receives "Fix GitHub issue 123 following our coding standards..."
253 294
254* Read-only Skills that shouldn't modify files295If you invoke a skill with arguments but the skill doesn't include `$ARGUMENTS`, Claude Code appends `ARGUMENTS: <your input>` to the end of the skill content so Claude still sees what you typed.
255* Skills with limited scope: for example, only data analysis, no file writing
256* Security-sensitive workflows where you want to restrict capabilities
257 296
258If `allowed-tools` is omitted, the Skill doesn't restrict tools. Claude uses its standard permission model and may ask you to approve tool usage.297## Advanced patterns
259 298
260<Note>299### Inject dynamic context
261 `allowed-tools` is only supported for Skills in Claude Code.
262</Note>
263 300
264### Use Skills with subagents301The `!`command\`\` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.
265 302
266[Subagents](/en/sub-agents) do not automatically inherit Skills from the main conversation. To give a custom subagent access to specific Skills, list them in the subagent's `skills` field in `.claude/agents/`:303This skill summarizes a pull request by fetching live PR data with the GitHub CLI. The `!`gh pr diff\`\` and other commands run first, and their output gets inserted into the prompt:
267 304
268```yaml theme={null}305```yaml theme={null}
269# .claude/agents/code-reviewer/AGENT.md
270---306---
271name: code-reviewer307name: pr-summary
272description: Review code for quality and best practices308description: Summarize changes in a pull request
273skills: pr-review, security-check309context: fork
310agent: Explore
311allowed-tools: Bash(gh:*)
274---312---
313
314## Pull request context
315- PR diff: !`gh pr diff`
316- PR comments: !`gh pr view --comments`
317- Changed files: !`gh pr diff --name-only`
318
319## Your task
320Summarize this pull request...
275```321```
276 322
277The listed Skills are loaded into the subagent's context when it starts. If the `skills` field is omitted, no Skills are preloaded for that subagent.323When this skill runs:
278 324
279<Note>3251. Each `!`command\`\` executes immediately (before Claude sees anything)
280 Built-in agents (Explore, Plan, Verify) and the Task tool do not have access to your Skills. Only custom subagents you define in `.claude/agents/` with an explicit `skills` field can use Skills.3262. The output replaces the placeholder in the skill content
281</Note>3273. Claude receives the fully-rendered prompt with actual PR data
282 328
283### Distribute Skills329This is preprocessing, not something Claude executes. Claude only sees the final result.
284 330
285You can share Skills in several ways:331<Tip>
332 To enable [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) in a skill, include the word "ultrathink" anywhere in your skill content.
333</Tip>
286 334
287* **Project Skills**: Commit `.claude/skills/` to version control. Anyone who clones the repository gets the Skills.335### Run skills in a subagent
288* **Plugins**: To share Skills across multiple repositories, create a `skills/` directory in your [plugin](/en/plugins) with Skill folders containing `SKILL.md` files. Distribute through a [plugin marketplace](/en/plugin-marketplaces).
289* **Enterprise**: Administrators can deploy Skills organization-wide through [managed settings](/en/iam#enterprise-managed-settings). See [Where Skills live](#where-skills-live) for enterprise Skill paths.
290 336
291## Examples337Add `context: fork` to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. It won't have access to your conversation history.
292 338
293These examples show common Skill patterns, from minimal single-file Skills to multi-file Skills with supporting documentation and scripts.339<Warning>
340 `context: fork` only makes sense for skills with explicit instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output.
341</Warning>
294 342
295### Simple Skill (single file)343Skills and [subagents](/en/sub-agents) work together in two directions:
296 344
297A minimal Skill needs only a `SKILL.md` file with frontmatter and instructions. This example helps Claude generate commit messages by examining staged changes:345| Approach | System prompt | Task | Also loads |
346| :--------------------------- | :---------------------------------------- | :-------------------------- | :--------------------------- |
347| Skill with `context: fork` | From agent type (`Explore`, `Plan`, etc.) | SKILL.md content | CLAUDE.md |
348| Subagent with `skills` field | Subagent's markdown body | Claude's delegation message | Preloaded skills + CLAUDE.md |
298 349
299```350With `context: fork`, you write the task in your skill and pick an agent type to execute it. For the inverse (defining a custom subagent that uses skills as reference material), see [Subagents](/en/sub-agents#preload-skills-into-subagents).
300commit-helper/351
301└── SKILL.md352#### Example: Research skill using Explore agent
302```353
354This skill runs research in a forked Explore agent. The skill content becomes the task, and the agent provides read-only tools optimized for codebase exploration:
303 355
304```yaml theme={null}356```yaml theme={null}
305---357---
306name: generating-commit-messages358name: deep-research
307description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.359description: Research a topic thoroughly
360context: fork
361agent: Explore
308---362---
309 363
310# Generating Commit Messages364Research $ARGUMENTS thoroughly:
311
312## Instructions
313 365
3141. Run `git diff --staged` to see changes3661. Find relevant files using Glob and Grep
3152. I'll suggest a commit message with:3672. Read and analyze the code
316 - Summary under 50 characters3683. Summarize findings with specific file references
317 - Detailed description
318 - Affected components
319
320## Best practices
321
322- Use present tense
323- Explain what and why, not how
324```369```
325 370
326### Use multiple files371When this skill runs:
327 372
328For complex Skills, use progressive disclosure to keep the main `SKILL.md` focused while providing detailed documentation in supporting files. This PDF processing Skill includes reference docs, utility scripts, and uses `allowed-tools` to restrict Claude to specific tools:3731. A new isolated context is created
3742. The subagent receives the skill content as its prompt ("Research \$ARGUMENTS thoroughly...")
3753. The `agent` field determines the execution environment (model, tools, and permissions)
3764. Results are summarized and returned to your main conversation
329 377
330```378The `agent` field specifies which subagent configuration to use. Options include built-in agents (`Explore`, `Plan`, `general-purpose`) or any custom subagent from `.claude/agents/`. If omitted, uses `general-purpose`.
331pdf-processing/
332├── SKILL.md # Overview and quick start
333├── FORMS.md # Form field mappings and filling instructions
334├── REFERENCE.md # API details for pypdf and pdfplumber
335└── scripts/
336 ├── fill_form.py # Utility to populate form fields
337 └── validate.py # Checks PDFs for required fields
338```
339 379
340**`SKILL.md`**:380### Restrict Claude's skill access
341 381
342````yaml theme={null}382By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Built-in commands like `/compact` and `/init` are not available through the Skill tool.
343name: pdf-processing
344description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
345allowed-tools: Read, Bash(python:*)
346 383
347# PDF Processing384Three ways to control which skills Claude can invoke:
348 385
349## Quick start386**Disable all skills** by denying the Skill tool in `/permissions`:
350 387
351Extract text:388```
352```python389# Add to deny rules:
353import pdfplumber390Skill
354with pdfplumber.open("doc.pdf") as pdf:
355 text = pdf.pages[0].extract_text()
356```391```
357 392
358For form filling, see [FORMS.md](FORMS.md).393**Allow or deny specific skills** using [permission rules](/en/iam):
359For detailed API reference, see [REFERENCE.md](REFERENCE.md).
360 394
361## Requirements395```
396# Allow only specific skills
397Skill(commit)
398Skill(review-pr:*)
362 399
363Packages must be installed in your environment:400# Deny specific skills
364```bash401Skill(deploy:*)
365pip install pypdf pdfplumber
366```402```
367````403
404Permission syntax: `Skill(name)` for exact match, `Skill(name:*)` for prefix match with any arguments.
405
406**Hide individual skills** by adding `disable-model-invocation: true` to their frontmatter. This removes the skill from Claude's context entirely.
368 407
369<Note>408<Note>
370 If your Skill requires external packages, list them in the description. Packages must be installed in your environment before Claude can use them.409 The `user-invocable` field only controls menu visibility, not Skill tool access. Use `disable-model-invocation: true` to block programmatic invocation.
371</Note>410</Note>
372 411
373## Troubleshooting412## Share skills
374
375### View and test Skills
376 413
377To see which Skills Claude has access to, ask Claude a question like "What Skills are available?" Claude loads all available Skill names and descriptions into the context window when a conversation starts, so it can list the Skills it currently has access to.414Skills can be distributed at different scopes depending on your audience:
378 415
379To test a specific Skill, ask Claude to do a task that matches the Skill's description. For example, if your Skill has the description "Reviews pull requests for code quality", ask Claude to "Review the changes in my current branch." Claude automatically uses the Skill when the request matches its description.416* **Project skills**: Commit `.claude/skills/` to version control
417* **Plugins**: Create a `skills/` directory in your [plugin](/en/plugins)
418* **Managed**: Deploy organization-wide through [managed settings](/en/iam#managed-settings)
380 419
381### Skill not triggering420### Generate visual output
382 421
383The description field is how Claude decides whether to use your Skill. Vague descriptions like "Helps with documents" don't give Claude enough information to match your Skill to relevant requests.422Skills can bundle and run scripts in any language, giving Claude capabilities beyond what's possible in a single prompt. One powerful pattern is generating visual output: interactive HTML files that open in your browser for exploring data, debugging, or creating reports.
384 423
385A good description answers two questions:424This example creates a codebase explorer: an interactive tree view where you can expand and collapse directories, see file sizes at a glance, and identify file types by color.
386 425
3871. **What does this Skill do?** List the specific capabilities.426Create the Skill directory:
3882. **When should Claude use it?** Include trigger terms users would mention.
389 427
390```yaml theme={null}428```bash theme={null}
391description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.429mkdir -p ~/.claude/skills/codebase-visualizer/scripts
392```430```
393 431
394This description works because it names specific actions (extract, fill, merge) and includes keywords users would say (PDF, forms, document extraction).432Create `~/.claude/skills/codebase-visualizer/SKILL.md`. The description tells Claude when to activate this Skill, and the instructions tell Claude to run the bundled script:
395
396### Skill doesn't load
397
398**Check the file path.** Skills must be in the correct directory with the exact filename `SKILL.md` (case-sensitive):
399 433
400| Type | Path |434````yaml theme={null}
401| :--------- | :---------------------------------------------------------------------- |435---
402| Personal | `~/.claude/skills/my-skill/SKILL.md` |436name: codebase-visualizer
403| Project | `.claude/skills/my-skill/SKILL.md` |437description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
404| Enterprise | See [Where Skills live](#where-skills-live) for platform-specific paths |438allowed-tools: Bash(python:*)
405| Plugin | `skills/my-skill/SKILL.md` inside the plugin directory |439---
406 440
407**Check the YAML syntax.** Invalid YAML in the frontmatter prevents the Skill from loading. The frontmatter must start with `---` on line 1 (no blank lines before it), end with `---` before the Markdown content, and use spaces for indentation (not tabs).441# Codebase Visualizer
408 442
409**Run debug mode.** Use `claude --debug` to see Skill loading errors.443Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.
410 444
411### Skill has errors445## Usage
412 446
413**Check dependencies are installed.** If your Skill uses external packages, they must be installed in your environment before Claude can use them.447Run the visualization script from your project root:
414 448
415**Check script permissions.** Scripts need execute permissions: `chmod +x scripts/*.py`449```bash
450python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
451```
416 452
417**Check file paths.** Use forward slashes (Unix style) in all paths. Use `scripts/helper.py`, not `scripts\helper.py`.453This creates `codebase-map.html` in the current directory and opens it in your default browser.
418 454
419### Multiple Skills conflict455## What the visualization shows
420 456
421If Claude uses the wrong Skill or seems confused between similar Skills, the descriptions are probably too similar. Make each description distinct by using specific trigger terms.457- **Collapsible directories**: Click folders to expand/collapse
458- **File sizes**: Displayed next to each file
459- **Colors**: Different colors for different file types
460- **Directory totals**: Shows aggregate size of each folder
461````
422 462
423For example, instead of two Skills with "data analysis" in both descriptions, differentiate them: one for "sales data in Excel files and CRM exports" and another for "log files and system metrics". The more specific your trigger terms, the easier it is for Claude to match the right Skill to your request.463Create `~/.claude/skills/codebase-visualizer/scripts/visualize.py`. This script scans a directory tree and generates a self-contained HTML file with:
464
465* A **summary sidebar** showing file count, directory count, total size, and number of file types
466* A **bar chart** breaking down the codebase by file type (top 8 by size)
467* A **collapsible tree** where you can expand and collapse directories, with color-coded file type indicators
468
469The script requires Python but uses only built-in libraries, so there are no packages to install:
470
471```python expandable theme={null}
472#!/usr/bin/env python3
473"""Generate an interactive collapsible tree visualization of a codebase."""
474
475import json
476import sys
477import webbrowser
478from pathlib import Path
479from collections import Counter
480
481IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}
482
483def scan(path: Path, stats: dict) -> dict:
484 result = {"name": path.name, "children": [], "size": 0}
485 try:
486 for item in sorted(path.iterdir()):
487 if item.name in IGNORE or item.name.startswith('.'):
488 continue
489 if item.is_file():
490 size = item.stat().st_size
491 ext = item.suffix.lower() or '(no ext)'
492 result["children"].append({"name": item.name, "size": size, "ext": ext})
493 result["size"] += size
494 stats["files"] += 1
495 stats["extensions"][ext] += 1
496 stats["ext_sizes"][ext] += size
497 elif item.is_dir():
498 stats["dirs"] += 1
499 child = scan(item, stats)
500 if child["children"]:
501 result["children"].append(child)
502 result["size"] += child["size"]
503 except PermissionError:
504 pass
505 return result
506
507def generate_html(data: dict, stats: dict, output: Path) -> None:
508 ext_sizes = stats["ext_sizes"]
509 total_size = sum(ext_sizes.values()) or 1
510 sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]
511 colors = {
512 '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',
513 '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',
514 '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',
515 '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',
516 }
517 lang_bars = "".join(
518 f'<div class="bar-row"><span class="bar-label">{ext}</span>'
519 f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'
520 f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'
521 for ext, size in sorted_exts
522 )
523 def fmt(b):
524 if b < 1024: return f"{b} B"
525 if b < 1048576: return f"{b/1024:.1f} KB"
526 return f"{b/1048576:.1f} MB"
527
528 html = f'''<!DOCTYPE html>
529<html><head>
530 <meta charset="utf-8"><title>Codebase Explorer</title>
531 <style>
532 body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}
533 .container {{ display: flex; height: 100vh; }}
534 .sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}
535 .main {{ flex: 1; padding: 20px; overflow-y: auto; }}
536 h1 {{ margin: 0 0 10px 0; font-size: 18px; }}
537 h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}
538 .stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}
539 .stat-value {{ font-weight: bold; }}
540 .bar-row {{ display: flex; align-items: center; margin: 6px 0; }}
541 .bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}
542 .bar {{ height: 18px; border-radius: 3px; }}
543 .bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}
544 .tree {{ list-style: none; padding-left: 20px; }}
545 details {{ cursor: pointer; }}
546 summary {{ padding: 4px 8px; border-radius: 4px; }}
547 summary:hover {{ background: #2d2d44; }}
548 .folder {{ color: #ffd700; }}
549 .file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}
550 .file:hover {{ background: #2d2d44; }}
551 .size {{ color: #888; margin-left: auto; font-size: 12px; }}
552 .dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}
553 </style>
554</head><body>
555 <div class="container">
556 <div class="sidebar">
557 <h1>📊 Summary</h1>
558 <div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>
559 <div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>
560 <div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>
561 <div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>
562 <h2>By file type</h2>
563 {lang_bars}
564 </div>
565 <div class="main">
566 <h1>📁 {data["name"]}</h1>
567 <ul class="tree" id="root"></ul>
568 </div>
569 </div>
570 <script>
571 const data = {json.dumps(data)};
572 const colors = {json.dumps(colors)};
573 function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}
574 function render(node, parent) {{
575 if (node.children) {{
576 const det = document.createElement('details');
577 det.open = parent === document.getElementById('root');
578 det.innerHTML = `<summary><span class="folder">📁 ${{node.name}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;
579 const ul = document.createElement('ul'); ul.className = 'tree';
580 node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));
581 node.children.forEach(c => render(c, ul));
582 det.appendChild(ul);
583 const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);
584 }} else {{
585 const li = document.createElement('li'); li.className = 'file';
586 li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{node.name}}<span class="size">${{fmt(node.size)}}</span>`;
587 parent.appendChild(li);
588 }}
589 }}
590 data.children.forEach(c => render(c, document.getElementById('root')));
591 </script>
592</body></html>'''
593 output.write_text(html)
594
595if __name__ == '__main__':
596 target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
597 stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}
598 data = scan(target, stats)
599 out = Path('codebase-map.html')
600 generate_html(data, stats, out)
601 print(f'Generated {out.absolute()}')
602 webbrowser.open(f'file://{out.absolute()}')
603```
424 604
425### Plugin Skills not appearing605To test, open Claude Code in any project and ask "Visualize this codebase." Claude runs the script, generates `codebase-map.html`, and opens it in your browser.
426 606
427**Symptom**: You installed a plugin from a marketplace, but its Skills don't appear when you ask Claude "What Skills are available?"607This pattern works for any visual output: dependency graphs, test coverage reports, API documentation, or database schema visualizations. The bundled script does the heavy lifting while Claude handles orchestration.
428 608
429**Solution**: Clear the plugin cache and reinstall:609## Troubleshooting
430 610
431```bash theme={null}611### Skill not triggering
432rm -rf ~/.claude/plugins/cache
433```
434 612
435Then restart Claude Code and reinstall the plugin:613If Claude doesn't use your skill when expected:
436 614
437```shell theme={null}6151. Check the description includes keywords users would naturally say
438/plugin install plugin-name@marketplace-name6162. Verify the skill appears in `What skills are available?`
439```6173. Try rephrasing your request to match the description more closely
6184. Invoke it directly with `/skill-name` if the skill is user-invocable
440 619
441This forces Claude Code to re-download and re-register the plugin's Skills.620### Skill triggers too often
442 621
443**If Skills still don't appear**, verify the plugin's directory structure is correct. Skills must be in a `skills/` directory at the plugin root:622If Claude uses your skill when you don't want it:
444 623
445```6241. Make the description more specific
446my-plugin/6252. Add `disable-model-invocation: true` if you only want manual invocation
447├── .claude-plugin/
448│ └── plugin.json
449└── skills/
450 └── my-skill/
451 └── SKILL.md
452```
453 626
454## Next steps627### Claude doesn't see all my skills
455 628
456<CardGroup cols={2}>629Skill descriptions are loaded into context so Claude knows what's available. If you have many skills, they may exceed the character budget (default 15,000 characters). Run `/context` to check for a warning about excluded skills.
457 <Card title="Authoring best practices" icon="lightbulb" href="https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices">
458 Write Skills that Claude can use effectively
459 </Card>
460 630
461 <Card title="Agent Skills overview" icon="book" href="https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview">631To increase the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable.
462 Learn how Skills work across Claude products
463 </Card>
464 632
465 <Card title="Use Skills in the Agent SDK" icon="cube" href="https://docs.claude.com/en/docs/agent-sdk/skills">633## Related resources
466 Use Skills programmatically with TypeScript and Python
467 </Card>
468 634
469 <Card title="Get started with Agent Skills" icon="rocket" href="https://docs.claude.com/en/docs/agents-and-tools/agent-skills/quickstart">635* **[Subagents](/en/sub-agents)**: delegate tasks to specialized agents
470 Create your first Skill636* **[Plugins](/en/plugins)**: package and distribute skills with other extensions
471 </Card>637* **[Hooks](/en/hooks)**: automate workflows around tool events
472</CardGroup>638* **[Memory](/en/memory)**: manage CLAUDE.md files for persistent context
639* **[Interactive mode](/en/interactive-mode#built-in-commands)**: built-in commands and shortcuts
640* **[Permissions](/en/iam)**: control tool and skill access
473 641
474 642
475---643---
