1# Agent Skills
2
3> Create, manage, and share Skills to extend Claude's capabilities in Claude Code.
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.
6
7## Prerequisites
8
9* Claude Code version 1.0 or later
10* Basic familiarity with [Claude Code](/en/docs/claude-code/quickstart)
11
12## What are Agent Skills?
13
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.
15
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**Benefits**:
19
20* Extend Claude's capabilities for your specific workflows
21* Share expertise across your team via git
22* Reduce repetitive prompting
23* Compose multiple Skills for complex tasks
24
25Learn more in the [Agent Skills overview](/en/docs/agents-and-tools/agent-skills/overview).
26
27<Note>
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).
29</Note>
30
31## Create a Skill
32
33Skills are stored as directories containing a `SKILL.md` file.
34
35### Personal Skills
36
37Personal Skills are available across all your projects. Store them in `~/.claude/skills/`:
38
39```bash theme={null}
40mkdir -p ~/.claude/skills/my-skill-name
41```
42
43**Use personal Skills for**:
44
45* Your individual workflows and preferences
46* Experimental Skills you're developing
47* Personal productivity tools
48
49### Project Skills
50
51Project Skills are shared with your team. Store them in `.claude/skills/` within your project:
52
53```bash theme={null}
54mkdir -p .claude/skills/my-skill-name
55```
56
57**Use project Skills for**:
58
59* Team workflows and conventions
60* Project-specific expertise
61* Shared utilities and scripts
62
63Project Skills are checked into git and automatically available to team members.
64
65### Plugin Skills
66
67Skills can also come from [Claude Code plugins](/en/docs/claude-code/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.
68
69## Write SKILL.md
70
71Create a `SKILL.md` file with YAML frontmatter and Markdown content:
72
73```yaml theme={null}
74---
75name: Your Skill Name
76description: Brief description of what this Skill does and when to use it
77---
78
79# Your Skill Name
80
81## Instructions
82Provide clear, step-by-step guidance for Claude.
83
84## Examples
85Show concrete examples of using this Skill.
86```
87
88The `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.
89
90See the [best practices guide](/en/docs/agents-and-tools/agent-skills/best-practices) for complete authoring guidance.
91
92## Add supporting files
93
94Create additional files alongside SKILL.md:
95
96```
97my-skill/
98├── SKILL.md (required)
99├── reference.md (optional documentation)
100├── examples.md (optional examples)
101├── scripts/
102│ └── helper.py (optional utility)
103└── templates/
104 └── template.txt (optional template)
105```
106
107Reference these files from SKILL.md:
108
109````markdown theme={null}
110For advanced usage, see [reference.md](reference.md).
111
112Run the helper script:
113```bash
114python scripts/helper.py input.txt
115```
116````
117
118Claude reads these files only when needed, using progressive disclosure to manage context efficiently.
119
120## Restrict tool access with allowed-tools
121
122Use the `allowed-tools` frontmatter field to limit which tools Claude can use when a Skill is active:
123
124```yaml theme={null}
125---
126name: Safe File Reader
127description: Read files without making changes. Use when you need read-only file access.
128allowed-tools: Read, Grep, Glob
129---
130
131# Safe File Reader
132
133This Skill provides read-only file access.
134
135## Instructions
1361. Use Read to view file contents
1372. Use Grep to search within files
1383. Use Glob to find files by pattern
139```
140
141When this Skill is active, Claude can only use the specified tools (Read, Grep, Glob) without needing to ask for permission. This is useful for:
142
143* Read-only Skills that shouldn't modify files
144* Skills with limited scope (e.g., only data analysis, no file writing)
145* Security-sensitive workflows where you want to restrict capabilities
146
147If `allowed-tools` is not specified, Claude will ask for permission to use tools as normal, following the standard permission model.
148
149<Note>
150 `allowed-tools` is only supported for Skills in Claude Code.
151</Note>
152
153## View available Skills
154
155Skills are automatically discovered by Claude from three sources:
156
157* Personal Skills: `~/.claude/skills/`
158* Project Skills: `.claude/skills/`
159* Plugin Skills: bundled with installed plugins
160
161**To view all available Skills**, ask Claude directly:
162
163```
164What Skills are available?
165```
166
167or
168
169```
170List all available Skills
171```
172
173This will show all Skills from all sources, including plugin Skills.
174
175**To inspect a specific Skill**, you can also check the filesystem:
176
177```bash theme={null}
178# List personal Skills
179ls ~/.claude/skills/
180
181# List project Skills (if in a project directory)
182ls .claude/skills/
183
184# View a specific Skill's content
185cat ~/.claude/skills/my-skill/SKILL.md
186```
187
188## Test a Skill
189
190After creating a Skill, test it by asking questions that match your description.
191
192**Example**: If your description mentions "PDF files":
193
194```
195Can you help me extract text from this PDF?
196```
197
198Claude 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.
199
200## Debug a Skill
201
202If Claude doesn't use your Skill, check these common issues:
203
204### Make description specific
205
206**Too vague**:
207
208```yaml theme={null}
209description: Helps with documents
210```
211
212**Specific**:
213
214```yaml theme={null}
215description: 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.
216```
217
218Include both what the Skill does and when to use it in the description.
219
220### Verify file path
221
222**Personal Skills**: `~/.claude/skills/skill-name/SKILL.md`
223**Project Skills**: `.claude/skills/skill-name/SKILL.md`
224
225Check the file exists:
226
227```bash theme={null}
228# Personal
229ls ~/.claude/skills/my-skill/SKILL.md
230
231# Project
232ls .claude/skills/my-skill/SKILL.md
233```
234
235### Check YAML syntax
236
237Invalid YAML prevents the Skill from loading. Verify the frontmatter:
238
239```bash theme={null}
240cat SKILL.md | head -n 10
241```
242
243Ensure:
244
245* Opening `---` on line 1
246* Closing `---` before Markdown content
247* Valid YAML syntax (no tabs, correct indentation)
248
249### View errors
250
251Run Claude Code with debug mode to see Skill loading errors:
252
253```bash theme={null}
254claude --debug
255```
256
257## Share Skills with your team
258
259**Recommended approach**: Distribute Skills through [plugins](/en/docs/claude-code/plugins).
260
261To share Skills via plugin:
262
2631. Create a plugin with Skills in the `skills/` directory
2642. Add the plugin to a marketplace
2653. Team members install the plugin
266
267For complete instructions, see [Add Skills to your plugin](/en/docs/claude-code/plugins#add-skills-to-your-plugin).
268
269You can also share Skills directly through project repositories:
270
271### Step 1: Add Skill to your project
272
273Create a project Skill:
274
275```bash theme={null}
276mkdir -p .claude/skills/team-skill
277# Create SKILL.md
278```
279
280### Step 2: Commit to git
281
282```bash theme={null}
283git add .claude/skills/
284git commit -m "Add team Skill for PDF processing"
285git push
286```
287
288### Step 3: Team members get Skills automatically
289
290When team members pull the latest changes, Skills are immediately available:
291
292```bash theme={null}
293git pull
294claude # Skills are now available
295```
296
297## Update a Skill
298
299Edit SKILL.md directly:
300
301```bash theme={null}
302# Personal Skill
303code ~/.claude/skills/my-skill/SKILL.md
304
305# Project Skill
306code .claude/skills/my-skill/SKILL.md
307```
308
309Changes take effect the next time you start Claude Code. If Claude Code is already running, restart it to load the updates.
310
311## Remove a Skill
312
313Delete the Skill directory:
314
315```bash theme={null}
316# Personal
317rm -rf ~/.claude/skills/my-skill
318
319# Project
320rm -rf .claude/skills/my-skill
321git commit -m "Remove unused Skill"
322```
323
324## Best practices
325
326### Keep Skills focused
327
328One Skill should address one capability:
329
330**Focused**:
331
332* "PDF form filling"
333* "Excel data analysis"
334* "Git commit messages"
335
336**Too broad**:
337
338* "Document processing" (split into separate Skills)
339* "Data tools" (split by data type or operation)
340
341### Write clear descriptions
342
343Help Claude discover when to use Skills by including specific triggers in your description:
344
345**Clear**:
346
347```yaml theme={null}
348description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
349```
350
351**Vague**:
352
353```yaml theme={null}
354description: For files
355```
356
357### Test with your team
358
359Have teammates use Skills and provide feedback:
360
361* Does the Skill activate when expected?
362* Are the instructions clear?
363* Are there missing examples or edge cases?
364
365### Document Skill versions
366
367You can document Skill versions in your SKILL.md content to track changes over time. Add a version history section:
368
369```markdown theme={null}
370# My Skill
371
372## Version History
373- v2.0.0 (2025-10-01): Breaking changes to API
374- v1.1.0 (2025-09-15): Added new features
375- v1.0.0 (2025-09-01): Initial release
376```
377
378This helps team members understand what changed between versions.
379
380## Troubleshooting
381
382### Claude doesn't use my Skill
383
384**Symptom**: You ask a relevant question but Claude doesn't use your Skill.
385
386**Check**: Is the description specific enough?
387
388Vague descriptions make discovery difficult. Include both what the Skill does and when to use it, with key terms users would mention.
389
390**Too generic**:
391
392```yaml theme={null}
393description: Helps with data
394```
395
396**Specific**:
397
398```yaml theme={null}
399description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
400```
401
402**Check**: Is the YAML valid?
403
404Run validation to check for syntax errors:
405
406```bash theme={null}
407# View frontmatter
408cat .claude/skills/my-skill/SKILL.md | head -n 15
409
410# Check for common issues
411# - Missing opening or closing ---
412# - Tabs instead of spaces
413# - Unquoted strings with special characters
414```
415
416**Check**: Is the Skill in the correct location?
417
418```bash theme={null}
419# Personal Skills
420ls ~/.claude/skills/*/SKILL.md
421
422# Project Skills
423ls .claude/skills/*/SKILL.md
424```
425
426### Skill has errors
427
428**Symptom**: The Skill loads but doesn't work correctly.
429
430**Check**: Are dependencies available?
431
432Claude will automatically install required dependencies (or ask for permission to install them) when it needs them.
433
434**Check**: Do scripts have execute permissions?
435
436```bash theme={null}
437chmod +x .claude/skills/my-skill/scripts/*.py
438```
439
440**Check**: Are file paths correct?
441
442Use forward slashes (Unix style) in all paths:
443
444**Correct**: `scripts/helper.py`
445**Wrong**: `scripts\helper.py` (Windows style)
446
447### Multiple Skills conflict
448
449**Symptom**: Claude uses the wrong Skill or seems confused between similar Skills.
450
451**Be specific in descriptions**: Help Claude choose the right Skill by using distinct trigger terms in your descriptions.
452
453Instead of:
454
455```yaml theme={null}
456# Skill 1
457description: For data analysis
458
459# Skill 2
460description: For analyzing data
461```
462
463Use:
464
465```yaml theme={null}
466# Skill 1
467description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.
468
469# Skill 2
470description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.
471```
472
473## Examples
474
475### Simple Skill (single file)
476
477```
478commit-helper/
479└── SKILL.md
480```
481
482```yaml theme={null}
483---
484name: Generating Commit Messages
485description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
486---
487
488# Generating Commit Messages
489
490## Instructions
491
4921. Run `git diff --staged` to see changes
4932. I'll suggest a commit message with:
494 - Summary under 50 characters
495 - Detailed description
496 - Affected components
497
498## Best practices
499
500- Use present tense
501- Explain what and why, not how
502```
503
504### Skill with tool permissions
505
506```
507code-reviewer/
508└── SKILL.md
509```
510
511```yaml theme={null}
512---
513name: Code Reviewer
514description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
515allowed-tools: Read, Grep, Glob
516---
517
518# Code Reviewer
519
520## Review checklist
521
5221. Code organization and structure
5232. Error handling
5243. Performance considerations
5254. Security concerns
5265. Test coverage
527
528## Instructions
529
5301. Read the target files using Read tool
5312. Search for patterns using Grep
5323. Find related files using Glob
5334. Provide detailed feedback on code quality
534```
535
536### Multi-file Skill
537
538```
539pdf-processing/
540├── SKILL.md
541├── FORMS.md
542├── REFERENCE.md
543└── scripts/
544 ├── fill_form.py
545 └── validate.py
546```
547
548**SKILL.md**:
549
550````yaml theme={null}
551---
552name: PDF Processing
553description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
554---
555
556# PDF Processing
557
558## Quick start
559
560Extract text:
561```python
562import pdfplumber
563with pdfplumber.open("doc.pdf") as pdf:
564 text = pdf.pages[0].extract_text()
565```
566
567For form filling, see [FORMS.md](FORMS.md).
568For detailed API reference, see [REFERENCE.md](REFERENCE.md).
569
570## Requirements
571
572Packages must be installed in your environment:
573```bash
574pip install pypdf pdfplumber
575```
576````
577
578<Note>
579 List required packages in the description. Packages must be installed in your environment before Claude can use them.
580</Note>
581
582Claude loads additional files only when needed.
583
584## Next steps
585
586<CardGroup cols={2}>
587 <Card title="Authoring best practices" icon="lightbulb" href="/en/docs/agents-and-tools/agent-skills/best-practices">
588 Write Skills that Claude can use effectively
589 </Card>
590
591 <Card title="Agent Skills overview" icon="book" href="/en/docs/agents-and-tools/agent-skills/overview">
592 Learn how Skills work across Claude products
593 </Card>
594
595 <Card title="Get started with Agent Skills" icon="rocket" href="/en/docs/agents-and-tools/agent-skills/quickstart">
596 Create your first Skill
597 </Card>
598</CardGroup>
