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.
4 4
5This guide shows you how to create, use, and manage Agent Skills in Claude Code. Skills are modular capabilities that extend Claude's functionality through organized folders containing instructions, scripts, and resources.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).
6 6
7## Prerequisites7A 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.
8 8
9* Claude Code version 1.0 or later9## Create your first Skill
10* Basic familiarity with [Claude Code](/en/quickstart)
11 10
12## What are Agent Skills?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.
13 12
14Agent Skills package expertise into discoverable capabilities. Each Skill consists of a `SKILL.md` file with instructions that Claude reads when relevant, plus optional supporting files like scripts and templates.13<Steps>
14 <Step title="Check available Skills">
15 Before creating a Skill, see what Skills Claude already has access to:
15 16
16**How Skills are invoked**: Skills are **model-invoked**—Claude autonomously decides when to use them based on your request and the Skill's description. This is different from slash commands, which are **user-invoked** (you explicitly type `/command` to trigger them).17 ```
18 What Skills are available?
19 ```
17 20
18**Benefits**:21 Claude will list any Skills currently loaded. You may see none, or you may see Skills from plugins or your organization.
22 </Step>
19 23
20* Extend Claude's capabilities for your specific workflows24 <Step title="Create the Skill directory">
21* Share expertise across your team via git25 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* Reduce repetitive prompting
23* Compose multiple Skills for complex tasks
24 26
25Learn more in the [Agent Skills overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview).27 ```bash theme={null}
28 mkdir -p ~/.claude/skills/explaining-code
29 ```
30 </Step>
26 31
27<Note>32 <Step title="Write SKILL.md">
28 For a deep dive into the architecture and real-world applications of Agent Skills, read our engineering blog: [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).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.
29</Note>
30 34
31## Create a Skill35 The `description` is especially important, because Claude uses it to decide when to apply the Skill.
32 36
33Skills are stored as directories containing a `SKILL.md` file.37 Create `~/.claude/skills/explaining-code/SKILL.md`:
34 38
35### Personal Skills39 ```yaml theme={null}
40 ---
41 name: explaining-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?"
43 ---
36 44
37Personal Skills are available across all your projects. Store them in `~/.claude/skills/`:45 When explaining code, always include:
38 46
39```bash theme={null}47 1. **Start with an analogy**: Compare the code to something from everyday life
40mkdir -p ~/.claude/skills/my-skill-name48 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
41```49 3. **Walk through the code**: Explain step-by-step what happens
50 4. **Highlight a gotcha**: What's a common mistake or misconception?
42 51
43**Use personal Skills for**:52 Keep explanations conversational. For complex concepts, use multiple analogies.
53 ```
54 </Step>
44 55
45* Your individual workflows and preferences56 <Step title="Load and verify the Skill">
46* Experimental Skills you're developing57 Exit and restart Claude Code to load the new Skill. Then verify it appears in the list:
47* Personal productivity tools
48 58
49### Project Skills59 ```
60 What Skills are available?
61 ```
50 62
51Project Skills are shared with your team. Store them in `.claude/skills/` within your project:63 You should see `explaining-code` in the list with its description.
64 </Step>
52 65
53```bash theme={null}66 <Step title="Test the Skill">
54mkdir -p .claude/skills/my-skill-name67 Open any file in your project and ask Claude a question that matches the Skill's description:
55```
56 68
57**Use project Skills for**:69 ```
70 How does this code work?
71 ```
58 72
59* Team workflows and conventions73 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."
60* Project-specific expertise74 </Step>
61* Shared utilities and scripts75</Steps>
62 76
63Project Skills are checked into git and automatically available to team members.77The rest of this guide covers how Skills work, configuration options, and troubleshooting.
64 78
65### Plugin Skills79## How Skills work
66 80
67Skills can also come from [Claude Code plugins](/en/plugins). Plugins may bundle Skills that are automatically available when the plugin is installed. These Skills work the same way as personal and project Skills.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.
68 82
69## Write SKILL.md83When you send a request, Claude follows these steps to find and use relevant Skills:
70 84
71Create a `SKILL.md` file with YAML frontmatter and Markdown content:85<Steps>
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>
72 89
73```yaml theme={null}90 <Step title="Activation">
74name: your-skill-name91 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.
75description: Brief description of what this Skill does and when to use it92 </Step>
76 93
77# Your Skill Name94 <Step title="Execution">
95 Claude follows the Skill's instructions, loading referenced files or running bundled scripts as needed.
96 </Step>
97</Steps>
78 98
79## Instructions99### Where Skills live
80Provide clear, step-by-step guidance for Claude.
81 100
82## Examples101Where you store a Skill determines who can use it:
83Show concrete examples of using this Skill.
84```
85 102
86**Field requirements**:103| Location | Path | Applies to |
104| :--------- | :----------------------------------------------- | :-------------------------------- |
105| Enterprise | See [managed settings](/en/iam#managed-settings) | All users in your organization |
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 |
87 109
88* `name`: Must use lowercase letters, numbers, and hyphens only (max 64 characters)110If two Skills have the same name, the higher row wins: managed overrides personal, personal overrides project, and project overrides plugin.
89* `description`: Brief description of what the Skill does and when to use it (max 1024 characters)
90 111
91The `description` field is critical for Claude to discover when to use your Skill. It should include both what the Skill does and when Claude should use it.112### When to use Skills versus other options
92 113
93See the [best practices guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance including validation rules.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.
94
95## Add supporting files
96 115
97Create additional files alongside SKILL.md:116| Use this | When you want to... | When it runs |
117| :--------------------------------------- | :------------------------------------------------------------------------- | :----------------------------------------- |
118| **Skills** | Give Claude specialized knowledge (e.g., "review PRs using our standards") | Claude chooses when relevant |
119| **[Slash commands](/en/slash-commands)** | Create reusable prompts (e.g., `/deploy staging`) | You type `/command` to run it |
120| **[CLAUDE.md](/en/memory)** | Set project-wide instructions (e.g., "use TypeScript strict mode") | Loaded into every conversation |
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 |
98 124
99```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.
100my-skill/
101├── SKILL.md (required)
102├── reference.md (optional documentation)
103├── examples.md (optional examples)
104├── scripts/
105│ └── helper.py (optional utility)
106└── templates/
107 └── template.txt (optional template)
108```
109 126
110Reference these files from SKILL.md: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.
111 128
112````markdown theme={null}129<Note>
113For advanced usage, see [reference.md](reference.md).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</Note>
114 132
115Run the helper script:133## Configure Skills
116```bash
117python scripts/helper.py input.txt
118```
119````
120 134
121Claude reads these files only when needed, using progressive disclosure to manage context efficiently.135This section covers Skill file structure, supporting files, tool restrictions, and distribution options.
122 136
123## Restrict tool access with allowed-tools137### Write SKILL.md
124 138
125Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active: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:
126 140
127```yaml theme={null}141```yaml theme={null}
128---142---
129name: safe-file-reader143name: your-skill-name
130description: Read files without making changes. Use when you need read-only file access.144description: Brief description of what this Skill does and when to use it
131allowed-tools: Read, Grep, Glob
132---145---
133 146
134# Safe File Reader147# Your Skill Name
135
136This Skill provides read-only file access.
137 148
138## Instructions149## Instructions
1391. Use Read to view file contents150Provide clear, step-by-step guidance for Claude.
1402. Use Grep to search within files
1413. Use Glob to find files by pattern
142```
143
144When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:
145
146* Read-only Skills that shouldn't modify files
147* Skills with limited scope: for example, only data analysis, no file writing
148* Security-sensitive workflows where you want to restrict capabilities
149
150If `allowed-tools` isn't specified, Claude will ask for permission to use tools as normal, following the standard permission model.
151
152<Note>
153 `allowed-tools` is only supported for Skills in Claude Code.
154</Note>
155
156## View available Skills
157
158Skills are automatically discovered by Claude from three sources:
159
160* Personal Skills: `~/.claude/skills/`
161* Project Skills: `.claude/skills/`
162* Plugin Skills: bundled with installed plugins
163
164**To view all available Skills**, ask Claude directly:
165
166```
167What Skills are available?
168```
169
170or
171
172```
173List all available Skills
174```
175
176This will show all Skills from all sources, including plugin Skills.
177
178**To inspect a specific Skill**, you can also check the filesystem:
179
180```bash theme={null}
181# List personal Skills
182ls ~/.claude/skills/
183
184# List project Skills (if in a project directory)
185ls .claude/skills/
186
187# View a specific Skill's content
188cat ~/.claude/skills/my-skill/SKILL.md
189```
190
191## Test a Skill
192
193After creating a Skill, test it by asking questions that match your description.
194
195**Example**: If your description mentions "PDF files":
196
197```
198Can you help me extract text from this PDF?
199```
200
201Claude autonomously decides to use your Skill if it matches the request—you don't need to explicitly invoke it. The Skill activates automatically based on the context of your question.
202
203## Debug a Skill
204
205If Claude doesn't use your Skill, check these common issues:
206
207### Make description specific
208
209**Too vague**:
210
211```yaml theme={null}
212description: Helps with documents
213```
214
215**Specific**:
216
217```yaml theme={null}
218description: 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.
219```
220
221Include both what the Skill does and when to use it in the description.
222
223### Verify file path
224
225**Personal Skills**: `~/.claude/skills/skill-name/SKILL.md`
226**Project Skills**: `.claude/skills/skill-name/SKILL.md`
227
228Check the file exists:
229
230```bash theme={null}
231# Personal
232ls ~/.claude/skills/my-skill/SKILL.md
233
234# Project
235ls .claude/skills/my-skill/SKILL.md
236```
237
238### Check YAML syntax
239
240Invalid YAML prevents the Skill from loading. Verify the frontmatter:
241
242```bash theme={null}
243cat SKILL.md | head -n 10
244```
245
246Ensure:
247
248* Opening `---` on line 1
249* Closing `---` before Markdown content
250* Valid YAML syntax (no tabs, correct indentation)
251
252### View errors
253
254Run Claude Code with debug mode to see Skill loading errors:
255 151
256```bash theme={null}152## Examples
257claude --debug153Show concrete examples of using this Skill.
258```154```
259 155
260## Share Skills with your team156#### Available metadata fields
261
262**Recommended approach**: Distribute Skills through [plugins](/en/plugins).
263
264To share Skills via plugin:
265
2661. Create a plugin with Skills in the `skills/` directory
2672. Add the plugin to a marketplace
2683. Team members install the plugin
269
270For complete instructions, see [Add Skills to your plugin](/en/plugins#add-skills-to-your-plugin).
271 157
272You can also share Skills directly through project repositories:158You can use the following fields in the YAML frontmatter:
273 159
274### Step 1: Add Skill to your project160| Field | Required | Description |
161| :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
162| `name` | Yes | Skill name. Must use lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |
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. |
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). |
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. |
275 166
276Create a project Skill: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.
277
278```bash theme={null}
279mkdir -p .claude/skills/team-skill
280# Create SKILL.md
281```
282 168
283### Step 2: Commit to git169### Update or delete a Skill
284 170
285```bash theme={null}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.
286git add .claude/skills/
287git commit -m "Add team Skill for PDF processing"
288git push
289```
290 172
291### Step 3: Team members get Skills automatically173### Add supporting files with progressive disclosure
292 174
293When team members pull the latest changes, Skills are immediately available: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.
294 176
295```bash theme={null}177This approach lets you bundle comprehensive documentation, examples, and scripts without consuming context upfront. Claude loads additional files only when the task requires them.
296git pull
297claude # Skills are now available
298```
299 178
300## Update a Skill179<Tip>Keep `SKILL.md` under 500 lines for optimal performance. If your content exceeds this, split detailed reference material into separate files.</Tip>
301 180
302Edit SKILL.md directly:181#### Example: multi-file Skill structure
303 182
304```bash theme={null}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:
305# Personal Skill
306code ~/.claude/skills/my-skill/SKILL.md
307 184
308# Project Skill
309code .claude/skills/my-skill/SKILL.md
310```185```
311 186my-skill/
312Changes take effect the next time you start Claude Code. If Claude Code is already running, restart it to load the updates.187├── SKILL.md (required - overview and navigation)
313 188├── reference.md (detailed API docs - loaded when needed)
314## Remove a Skill189├── examples.md (usage examples - loaded when needed)
315 190└── scripts/
316Delete the Skill directory:191 └── helper.py (utility script - executed, not loaded)
317
318```bash theme={null}
319# Personal
320rm -rf ~/.claude/skills/my-skill
321
322# Project
323rm -rf .claude/skills/my-skill
324git commit -m "Remove unused Skill"
325```192```
326 193
327## Best practices194The `SKILL.md` file references these supporting files so Claude knows they exist:
328
329### Keep Skills focused
330
331One Skill should address one capability:
332
333**Focused**:
334 195
335* "PDF form filling"196````markdown theme={null}
336* "Excel data analysis"197## Overview
337* "Git commit messages"
338
339**Too broad**:
340 198
341* "Document processing" (split into separate Skills)199[Essential instructions here]
342* "Data tools" (split by data type or operation)
343 200
344### Write clear descriptions201## Additional resources
345 202
346Help Claude discover when to use Skills by including specific triggers in your description:203- For complete API details, see [reference.md](reference.md)
204- For usage examples, see [examples.md](examples.md)
347 205
348**Clear**:206## Utility scripts
349 207
350```yaml theme={null}208To validate input files, run the helper script. It checks for required fields and returns any validation errors:
351description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.209```bash
352```210python scripts/helper.py input.txt
353
354**Vague**:
355
356```yaml theme={null}
357description: For files
358```211```
212````
359 213
360### Test with your team214<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>
361
362Have teammates use Skills and provide feedback:
363 215
364* Does the Skill activate when expected?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:
365* Are the instructions clear?
366* Are there missing examples or edge cases?
367 217
368### Document Skill versions218* Complex validation logic that would be verbose to describe in prose
219* Data processing that's more reliable as tested code than generated code
220* Operations that benefit from consistency across uses
369 221
370You can document Skill versions in your SKILL.md content to track changes over time. Add a version history section:222In `SKILL.md`, tell Claude to run the script rather than read it:
371 223
372```markdown theme={null}224```markdown theme={null}
373# My Skill225Run the validation script to check the form:
374 226python scripts/validate_form.py input.pdf
375## Version History
376- v2.0.0 (2025-10-01): Breaking changes to API
377- v1.1.0 (2025-09-15): Added new features
378- v1.0.0 (2025-09-01): Initial release
379```227```
380 228
381This helps team members understand what changed between versions.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).
382 230
383## Troubleshooting231### Restrict tool access with allowed-tools
384
385### Claude doesn't use my Skill
386
387**Symptom**: You ask a relevant question but Claude doesn't use your Skill.
388
389**Check**: Is the description specific enough?
390
391Vague descriptions make discovery difficult. Include both what the Skill does and when to use it, with key terms users would mention.
392
393**Too generic**:
394
395```yaml theme={null}
396description: Helps with data
397```
398 232
399**Specific**:233Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active:
400 234
401```yaml theme={null}235```yaml theme={null}
402description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.236---
403```237name: reading-files-safely
404 238description: Read files without making changes. Use when you need read-only file access.
405**Check**: Is the YAML valid?239allowed-tools: Read, Grep, Glob
240---
406 241
407Run validation to check for syntax errors:242# Safe File Reader
408 243
409```bash theme={null}244This Skill provides read-only file access.
410# View frontmatter
411cat .claude/skills/my-skill/SKILL.md | head -n 15
412 245
413# Check for common issues246## Instructions
414# - Missing opening or closing ---2471. Use Read to view file contents
415# - Tabs instead of spaces2482. Use Grep to search within files
416# - Unquoted strings with special characters2493. Use Glob to find files by pattern
417```250```
418 251
419**Check**: Is the Skill in the correct location?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:
420
421```bash theme={null}
422# Personal Skills
423ls ~/.claude/skills/*/SKILL.md
424
425# Project Skills
426ls .claude/skills/*/SKILL.md
427```
428 253
429### Skill has errors254* Read-only Skills that shouldn't modify files
255* Skills with limited scope: for example, only data analysis, no file writing
256* Security-sensitive workflows where you want to restrict capabilities
430 257
431**Symptom**: The Skill loads but doesn't work correctly.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.
432 259
433**Check**: Are dependencies available?260<Note>
261 `allowed-tools` is only supported for Skills in Claude Code.
262</Note>
434 263
435Claude will automatically install required dependencies (or ask for permission to install them) when it needs them.264### Use Skills with subagents
436 265
437**Check**: Do scripts have execute permissions?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/`:
438 267
439```bash theme={null}268```yaml theme={null}
440chmod +x .claude/skills/my-skill/scripts/*.py269# .claude/agents/code-reviewer/AGENT.md
270---
271name: code-reviewer
272description: Review code for quality and best practices
273skills: pr-review, security-check
274---
441```275```
442 276
443**Check**: Are file paths correct?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.
444
445Use forward slashes (Unix style) in all paths:
446
447**Correct**: `scripts/helper.py`
448**Wrong**: `scripts\helper.py` (Windows style)
449
450### Multiple Skills conflict
451
452**Symptom**: Claude uses the wrong Skill or seems confused between similar Skills.
453
454**Be specific in descriptions**: Help Claude choose the right Skill by using distinct trigger terms in your descriptions.
455
456Instead of:
457
458```yaml theme={null}
459# Skill 1
460description: For data analysis
461 278
462# Skill 2279<Note>
463description: For analyzing data280 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.
464```281</Note>
465 282
466Use:283### Distribute Skills
467 284
468```yaml theme={null}285You can share Skills in several ways:
469# Skill 1
470description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.
471 286
472# Skill 2287* **Project Skills**: Commit `.claude/skills/` to version control. Anyone who clones the repository gets the Skills.
473description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.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).
474```289* **Managed**: Administrators can deploy Skills organization-wide through [managed settings](/en/iam#managed-settings). See [Where Skills live](#where-skills-live) for managed Skill paths.
475 290
476## Examples291## Examples
477 292
293These examples show common Skill patterns, from minimal single-file Skills to multi-file Skills with supporting documentation and scripts.
294
478### Simple Skill (single file)295### Simple Skill (single file)
479 296
297A minimal Skill needs only a `SKILL.md` file with frontmatter and instructions. This example helps Claude generate commit messages by examining staged changes:
298
480```299```
481commit-helper/300commit-helper/
482└── SKILL.md301└── SKILL.md
506- Explain what and why, not how323- Explain what and why, not how
507```324```
508 325
509### Skill with tool permissions326### Use multiple files
510
511```
512code-reviewer/
513└── SKILL.md
514```
515
516```yaml theme={null}
517name: code-reviewer
518description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
519allowed-tools: Read, Grep, Glob
520 327
521# Code Reviewer328For 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:
522
523## Review checklist
524
5251. Code organization and structure
5262. Error handling
5273. Performance considerations
5284. Security concerns
5295. Test coverage
530
531## Instructions
532
5331. Read the target files using Read tool
5342. Search for patterns using Grep
5353. Find related files using Glob
5364. Provide detailed feedback on code quality
537```
538
539### Multi-file Skill
540 329
541```330```
542pdf-processing/331pdf-processing/
543├── SKILL.md332├── SKILL.md # Overview and quick start
544├── FORMS.md333├── FORMS.md # Form field mappings and filling instructions
545├── REFERENCE.md334├── REFERENCE.md # API details for pypdf and pdfplumber
546└── scripts/335└── scripts/
547 ├── fill_form.py336 ├── fill_form.py # Utility to populate form fields
548 └── validate.py337 └── validate.py # Checks PDFs for required fields
549```338```
550 339
551**SKILL.md**:340**`SKILL.md`**:
552 341
553````yaml theme={null}342````yaml theme={null}
554---343---
555name: pdf-processing344name: pdf-processing
556description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.345description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
346allowed-tools: Read, Bash(python:*)
557---347---
558 348
559# PDF Processing349# PDF Processing
581````369````
582 370
583<Note>371<Note>
584 List required packages in the description. Packages must be installed in your environment before Claude can use them.372 If your Skill requires external packages, list them in the description. Packages must be installed in your environment before Claude can use them.
585</Note>373</Note>
586 374
587Claude loads additional files only when needed.375## Troubleshooting
376
377### View and test Skills
378
379To 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.
380
381To 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.
382
383### Skill not triggering
384
385The 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.
386
387A good description answers two questions:
388
3891. **What does this Skill do?** List the specific capabilities.
3902. **When should Claude use it?** Include trigger terms users would mention.
391
392```yaml theme={null}
393description: 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.
394```
395
396This description works because it names specific actions (extract, fill, merge) and includes keywords users would say (PDF, forms, document extraction).
397
398### Skill doesn't load
399
400**Check the file path.** Skills must be in the correct directory with the exact filename `SKILL.md` (case-sensitive):
401
402| Type | Path |
403| :--------- | :---------------------------------------------------------------------- |
404| Personal | `~/.claude/skills/my-skill/SKILL.md` |
405| Project | `.claude/skills/my-skill/SKILL.md` |
406| Enterprise | See [Where Skills live](#where-skills-live) for platform-specific paths |
407| Plugin | `skills/my-skill/SKILL.md` inside the plugin directory |
408
409**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).
410
411**Run debug mode.** Use `claude --debug` to see Skill loading errors.
412
413### Skill has errors
414
415**Check dependencies are installed.** If your Skill uses external packages, they must be installed in your environment before Claude can use them.
416
417**Check script permissions.** Scripts need execute permissions: `chmod +x scripts/*.py`
418
419**Check file paths.** Use forward slashes (Unix style) in all paths. Use `scripts/helper.py`, not `scripts\helper.py`.
420
421### Multiple Skills conflict
422
423If 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.
424
425For 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.
426
427### Plugin Skills not appearing
428
429**Symptom**: You installed a plugin from a marketplace, but its Skills don't appear when you ask Claude "What Skills are available?"
430
431**Solution**: Clear the plugin cache and reinstall:
432
433```bash theme={null}
434rm -rf ~/.claude/plugins/cache
435```
436
437Then restart Claude Code and reinstall the plugin:
438
439```shell theme={null}
440/plugin install plugin-name@marketplace-name
441```
442
443This forces Claude Code to re-download and re-register the plugin's Skills.
444
445**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:
446
447```
448my-plugin/
449├── .claude-plugin/
450│ └── plugin.json
451└── skills/
452 └── my-skill/
453 └── SKILL.md
454```
588 455
589## Next steps456## Next steps
590 457
