1# Skill authoring best practices
2 
3> Learn how to write effective Skills that Claude can discover and use successfully.
4 
5Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively.
6 
7For conceptual background on how Skills work, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview).
8 
9## Core principles
10 
11### Concise is key
12 
13The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
14 
15* The system prompt
16* Conversation history
17* Other Skills' metadata
18* Your actual request
19 
20Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.
21 
22**Default assumption**: Claude is already very smart
23 
24Only add context Claude doesn't already have. Challenge each piece of information:
25 
26* "Does Claude really need this explanation?"
27* "Can I assume Claude knows this?"
28* "Does this paragraph justify its token cost?"
29 
30**Good example: Concise** (approximately 50 tokens):
31 
32````markdown  theme={null}
33## Extract PDF text
34 
35Use pdfplumber for text extraction:
36 
37```python
38import pdfplumber
39 
40with pdfplumber.open("file.pdf") as pdf:
41    text = pdf.pages[0].extract_text()
42```
43````
44 
45**Bad example: Too verbose** (approximately 150 tokens):
46 
47```markdown  theme={null}
48## Extract PDF text
49 
50PDF (Portable Document Format) files are a common file format that contains
51text, images, and other content. To extract text from a PDF, you'll need to
52use a library. There are many libraries available for PDF processing, but we
53recommend pdfplumber because it's easy to use and handles most cases well.
54First, you'll need to install it using pip. Then you can use the code below...
55```
56 
57The concise version assumes Claude knows what PDFs are and how libraries work.
58 
59### Set appropriate degrees of freedom
60 
61Match the level of specificity to the task's fragility and variability.
62 
63**High freedom** (text-based instructions):
64 
65Use when:
66 
67* Multiple approaches are valid
68* Decisions depend on context
69* Heuristics guide the approach
70 
71Example:
72 
73```markdown  theme={null}
74## Code review process
75 
761. Analyze the code structure and organization
772. Check for potential bugs or edge cases
783. Suggest improvements for readability and maintainability
794. Verify adherence to project conventions
80```
81 
82**Medium freedom** (pseudocode or scripts with parameters):
83 
84Use when:
85 
86* A preferred pattern exists
87* Some variation is acceptable
88* Configuration affects behavior
89 
90Example:
91 
92````markdown  theme={null}
93## Generate report
94 
95Use this template and customize as needed:
96 
97```python
98def generate_report(data, format="markdown", include_charts=True):
99    # Process data
100    # Generate output in specified format
101    # Optionally include visualizations
102```
103````
104 
105**Low freedom** (specific scripts, few or no parameters):
106 
107Use when:
108 
109* Operations are fragile and error-prone
110* Consistency is critical
111* A specific sequence must be followed
112 
113Example:
114 
115````markdown  theme={null}
116## Database migration
117 
118Run exactly this script:
119 
120```bash
121python scripts/migrate.py --verify --backup
122```
123 
124Do not modify the command or add additional flags.
125````
126 
127**Analogy**: Think of Claude as a robot exploring a path:
128 
129* **Narrow bridge with cliffs on both sides**: There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.
130* **Open field with no hazards**: Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach.
131 
132### Test with all models you plan to use
133 
134Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with all the models you plan to use it with.
135 
136**Testing considerations by model**:
137 
138* **Claude Haiku** (fast, economical): Does the Skill provide enough guidance?
139* **Claude Sonnet** (balanced): Is the Skill clear and efficient?
140* **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining?
141 
142What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them.
143 
144## Skill structure
145 
146<Note>
147  **YAML Frontmatter**: The SKILL.md frontmatter requires two fields:
148 
149  * `name` - Human-readable name of the Skill (64 characters maximum)
150  * `description` - One-line description of what the Skill does and when to use it (1024 characters maximum)
151 
152  For complete Skill structure details, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure).
153</Note>
154 
155### Naming conventions
156 
157Use consistent naming patterns to make Skills easier to reference and discuss. We recommend using **gerund form** (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.
158 
159**Good naming examples (gerund form)**:
160 
161* "Processing PDFs"
162* "Analyzing spreadsheets"
163* "Managing databases"
164* "Testing code"
165* "Writing documentation"
166 
167**Acceptable alternatives**:
168 
169* Noun phrases: "PDF Processing", "Spreadsheet Analysis"
170* Action-oriented: "Process PDFs", "Analyze Spreadsheets"
171 
172**Avoid**:
173 
174* Vague names: "Helper", "Utils", "Tools"
175* Overly generic: "Documents", "Data", "Files"
176* Inconsistent patterns within your skill collection
177 
178Consistent naming makes it easier to:
179 
180* Reference Skills in documentation and conversations
181* Understand what a Skill does at a glance
182* Organize and search through multiple Skills
183* Maintain a professional, cohesive skill library
184 
185### Writing effective descriptions
186 
187The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
188 
189<Warning>
190  **Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
191 
192  * **Good:** "Processes Excel files and generates reports"
193  * **Avoid:** "I can help you process Excel files"
194  * **Avoid:** "You can use this to process Excel files"
195</Warning>
196 
197**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.
198 
199Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details.
200 
201Effective examples:
202 
203**PDF Processing skill:**
204 
205```yaml  theme={null}
206description: 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.
207```
208 
209**Excel Analysis skill:**
210 
211```yaml  theme={null}
212description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
213```
214 
215**Git Commit Helper skill:**
216 
217```yaml  theme={null}
218description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
219```
220 
221Avoid vague descriptions like these:
222 
223```yaml  theme={null}
224description: Helps with documents
225```
226 
227```yaml  theme={null}
228description: Processes data
229```
230 
231```yaml  theme={null}
232description: Does stuff with files
233```
234 
235### Progressive disclosure patterns
236 
237SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the overview.
238 
239**Practical guidance:**
240 
241* Keep SKILL.md body under 500 lines for optimal performance
242* Split content into separate files when approaching this limit
243* Use the patterns below to organize instructions, code, and resources effectively
244 
245#### Visual overview: From simple to complex
246 
247A basic Skill starts with just a SKILL.md file containing metadata and instructions:
248 
249<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=87782ff239b297d9a9e8e1b72ed72db9" alt="Simple SKILL.md file showing YAML frontmatter and markdown body" data-og-width="2048" width="2048" data-og-height="1153" height="1153" data-path="images/agent-skills-simple-file.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=c61cc33b6f5855809907f7fda94cd80e 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=90d2c0c1c76b36e8d485f49e0810dbfd 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=ad17d231ac7b0bea7e5b4d58fb4aeabb 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f5d0a7a3c668435bb0aee9a3a8f8c329 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0e927c1af9de5799cfe557d12249f6e6 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-simple-file.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=46bbb1a51dd4c8202a470ac8c80a893d 2500w" />
250 
251As your Skill grows, you can bundle additional content that Claude loads only when needed:
252 
253<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=a5e0aa41e3d53985a7e3e43668a33ea3" alt="Bundling additional reference files like reference.md and forms.md." data-og-width="2048" width="2048" data-og-height="1327" height="1327" data-path="images/agent-skills-bundling-content.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=f8a0e73783e99b4a643d79eac86b70a2 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=dc510a2a9d3f14359416b706f067904a 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=82cd6286c966303f7dd914c28170e385 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=56f3be36c77e4fe4b523df209a6824c6 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=d22b5161b2075656417d56f41a74f3dd 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-bundling-content.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=3dd4bdd6850ffcc96c6c45fcb0acd6eb 2500w" />
254 
255The complete Skill directory structure might look like this:
256 
257```
258pdf/
259├── SKILL.md              # Main instructions (loaded when triggered)
260├── FORMS.md              # Form-filling guide (loaded as needed)
261├── reference.md          # API reference (loaded as needed)
262├── examples.md           # Usage examples (loaded as needed)
263└── scripts/
264    ├── analyze_form.py   # Utility script (executed, not loaded)
265    ├── fill_form.py      # Form filling script
266    └── validate.py       # Validation script
267```
268 
269#### Pattern 1: High-level guide with references
270 
271````markdown  theme={null}
272---
273name: PDF Processing
274description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
275---
276 
277# PDF Processing
278 
279## Quick start
280 
281Extract text with pdfplumber:
282```python
283import pdfplumber
284with pdfplumber.open("file.pdf") as pdf:
285    text = pdf.pages[0].extract_text()
286```
287 
288## Advanced features
289 
290**Form filling**: See [FORMS.md](FORMS.md) for complete guide
291**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
292**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
293````
294 
295Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
296 
297#### Pattern 2: Domain-specific organization
298 
299For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused.
300 
301```
302bigquery-skill/
303├── SKILL.md (overview and navigation)
304└── reference/
305    ├── finance.md (revenue, billing metrics)
306    ├── sales.md (opportunities, pipeline)
307    ├── product.md (API usage, features)
308    └── marketing.md (campaigns, attribution)
309```
310 
311````markdown SKILL.md theme={null}
312# BigQuery Data Analysis
313 
314## Available datasets
315 
316**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
317**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
318**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
319**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
320 
321## Quick search
322 
323Find specific metrics using grep:
324 
325```bash
326grep -i "revenue" reference/finance.md
327grep -i "pipeline" reference/sales.md
328grep -i "api usage" reference/product.md
329```
330````
331 
332#### Pattern 3: Conditional details
333 
334Show basic content, link to advanced content:
335 
336```markdown  theme={null}
337# DOCX Processing
338 
339## Creating documents
340 
341Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
342 
343## Editing documents
344 
345For simple edits, modify the XML directly.
346 
347**For tracked changes**: See [REDLINING.md](REDLINING.md)
348**For OOXML details**: See [OOXML.md](OOXML.md)
349```
350 
351Claude reads REDLINING.md or OOXML.md only when the user needs those features.
352 
353### Avoid deeply nested references
354 
355Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.
356 
357**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed.
358 
359**Bad example: Too deep**:
360 
361```markdown  theme={null}
362# SKILL.md
363See [advanced.md](advanced.md)...
364 
365# advanced.md
366See [details.md](details.md)...
367 
368# details.md
369Here's the actual information...
370```
371 
372**Good example: One level deep**:
373 
374```markdown  theme={null}
375# SKILL.md
376 
377**Basic usage**: [instructions in SKILL.md]
378**Advanced features**: See [advanced.md](advanced.md)
379**API reference**: See [reference.md](reference.md)
380**Examples**: See [examples.md](examples.md)
381```
382 
383### Structure longer reference files with table of contents
384 
385For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.
386 
387**Example**:
388 
389```markdown  theme={null}
390# API Reference
391 
392## Contents
393- Authentication and setup
394- Core methods (create, read, update, delete)
395- Advanced features (batch operations, webhooks)
396- Error handling patterns
397- Code examples
398 
399## Authentication and setup
400...
401 
402## Core methods
403...
404```
405 
406Claude can then read the complete file or jump to specific sections as needed.
407 
408For details on how this filesystem-based architecture enables progressive disclosure, see the [Runtime environment](#runtime-environment) section in the Advanced section below.
409 
410## Workflows and feedback loops
411 
412### Use workflows for complex tasks
413 
414Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses.
415 
416**Example 1: Research synthesis workflow** (for Skills without code):
417 
418````markdown  theme={null}
419## Research synthesis workflow
420 
421Copy this checklist and track your progress:
422 
423```
424Research Progress:
425- [ ] Step 1: Read all source documents
426- [ ] Step 2: Identify key themes
427- [ ] Step 3: Cross-reference claims
428- [ ] Step 4: Create structured summary
429- [ ] Step 5: Verify citations
430```
431 
432**Step 1: Read all source documents**
433 
434Review each document in the `sources/` directory. Note the main arguments and supporting evidence.
435 
436**Step 2: Identify key themes**
437 
438Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?
439 
440**Step 3: Cross-reference claims**
441 
442For each major claim, verify it appears in the source material. Note which source supports each point.
443 
444**Step 4: Create structured summary**
445 
446Organize findings by theme. Include:
447- Main claim
448- Supporting evidence from sources
449- Conflicting viewpoints (if any)
450 
451**Step 5: Verify citations**
452 
453Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
454````
455 
456This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multi-step process.
457 
458**Example 2: PDF form filling workflow** (for Skills with code):
459 
460````markdown  theme={null}
461## PDF form filling workflow
462 
463Copy this checklist and check off items as you complete them:
464 
465```
466Task Progress:
467- [ ] Step 1: Analyze the form (run analyze_form.py)
468- [ ] Step 2: Create field mapping (edit fields.json)
469- [ ] Step 3: Validate mapping (run validate_fields.py)
470- [ ] Step 4: Fill the form (run fill_form.py)
471- [ ] Step 5: Verify output (run verify_output.py)
472```
473 
474**Step 1: Analyze the form**
475 
476Run: `python scripts/analyze_form.py input.pdf`
477 
478This extracts form fields and their locations, saving to `fields.json`.
479 
480**Step 2: Create field mapping**
481 
482Edit `fields.json` to add values for each field.
483 
484**Step 3: Validate mapping**
485 
486Run: `python scripts/validate_fields.py fields.json`
487 
488Fix any validation errors before continuing.
489 
490**Step 4: Fill the form**
491 
492Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
493 
494**Step 5: Verify output**
495 
496Run: `python scripts/verify_output.py output.pdf`
497 
498If verification fails, return to Step 2.
499````
500 
501Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multi-step workflows.
502 
503### Implement feedback loops
504 
505**Common pattern**: Run validator → fix errors → repeat
506 
507This pattern greatly improves output quality.
508 
509**Example 1: Style guide compliance** (for Skills without code):
510 
511```markdown  theme={null}
512## Content review process
513 
5141. Draft your content following the guidelines in STYLE_GUIDE.md
5152. Review against the checklist:
516   - Check terminology consistency
517   - Verify examples follow the standard format
518   - Confirm all required sections are present
5193. If issues found:
520   - Note each issue with specific section reference
521   - Revise the content
522   - Review the checklist again
5234. Only proceed when all requirements are met
5245. Finalize and save the document
525```
526 
527This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE\_GUIDE.md, and Claude performs the check by reading and comparing.
528 
529**Example 2: Document editing process** (for Skills with code):
530 
531```markdown  theme={null}
532## Document editing process
533 
5341. Make your edits to `word/document.xml`
5352. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
5363. If validation fails:
537   - Review the error message carefully
538   - Fix the issues in the XML
539   - Run validation again
5404. **Only proceed when validation passes**
5415. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
5426. Test the output document
543```
544 
545The validation loop catches errors early.
546 
547## Content guidelines
548 
549### Avoid time-sensitive information
550 
551Don't include information that will become outdated:
552 
553**Bad example: Time-sensitive** (will become wrong):
554 
555```markdown  theme={null}
556If you're doing this before August 2025, use the old API.
557After August 2025, use the new API.
558```
559 
560**Good example** (use "old patterns" section):
561 
562```markdown  theme={null}
563## Current method
564 
565Use the v2 API endpoint: `api.example.com/v2/messages`
566 
567## Old patterns
568 
569<details>
570<summary>Legacy v1 API (deprecated 2025-08)</summary>
571 
572The v1 API used: `api.example.com/v1/messages`
573 
574This endpoint is no longer supported.
575</details>
576```
577 
578The old patterns section provides historical context without cluttering the main content.
579 
580### Use consistent terminology
581 
582Choose one term and use it throughout the Skill:
583 
584**Good - Consistent**:
585 
586* Always "API endpoint"
587* Always "field"
588* Always "extract"
589 
590**Bad - Inconsistent**:
591 
592* Mix "API endpoint", "URL", "API route", "path"
593* Mix "field", "box", "element", "control"
594* Mix "extract", "pull", "get", "retrieve"
595 
596Consistency helps Claude understand and follow instructions.
597 
598## Common patterns
599 
600### Template pattern
601 
602Provide templates for output format. Match the level of strictness to your needs.
603 
604**For strict requirements** (like API responses or data formats):
605 
606````markdown  theme={null}
607## Report structure
608 
609ALWAYS use this exact template structure:
610 
611```markdown
612# [Analysis Title]
613 
614## Executive summary
615[One-paragraph overview of key findings]
616 
617## Key findings
618- Finding 1 with supporting data
619- Finding 2 with supporting data
620- Finding 3 with supporting data
621 
622## Recommendations
6231. Specific actionable recommendation
6242. Specific actionable recommendation
625```
626````
627 
628**For flexible guidance** (when adaptation is useful):
629 
630````markdown  theme={null}
631## Report structure
632 
633Here is a sensible default format, but use your best judgment based on the analysis:
634 
635```markdown
636# [Analysis Title]
637 
638## Executive summary
639[Overview]
640 
641## Key findings
642[Adapt sections based on what you discover]
643 
644## Recommendations
645[Tailor to the specific context]
646```
647 
648Adjust sections as needed for the specific analysis type.
649````
650 
651### Examples pattern
652 
653For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting:
654 
655````markdown  theme={null}
656## Commit message format
657 
658Generate commit messages following these examples:
659 
660**Example 1:**
661Input: Added user authentication with JWT tokens
662Output:
663```
664feat(auth): implement JWT-based authentication
665 
666Add login endpoint and token validation middleware
667```
668 
669**Example 2:**
670Input: Fixed bug where dates displayed incorrectly in reports
671Output:
672```
673fix(reports): correct date formatting in timezone conversion
674 
675Use UTC timestamps consistently across report generation
676```
677 
678**Example 3:**
679Input: Updated dependencies and refactored error handling
680Output:
681```
682chore: update dependencies and refactor error handling
683 
684- Upgrade lodash to 4.17.21
685- Standardize error response format across endpoints
686```
687 
688Follow this style: type(scope): brief description, then detailed explanation.
689````
690 
691Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
692 
693### Conditional workflow pattern
694 
695Guide Claude through decision points:
696 
697```markdown  theme={null}
698## Document modification workflow
699 
7001. Determine the modification type:
701 
702   **Creating new content?** → Follow "Creation workflow" below
703   **Editing existing content?** → Follow "Editing workflow" below
704 
7052. Creation workflow:
706   - Use docx-js library
707   - Build document from scratch
708   - Export to .docx format
709 
7103. Editing workflow:
711   - Unpack existing document
712   - Modify XML directly
713   - Validate after each change
714   - Repack when complete
715```
716 
717<Tip>
718  If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand.
719</Tip>
720 
721## Evaluation and iteration
722 
723### Build evaluations first
724 
725**Create evaluations BEFORE writing extensive documentation.** This ensures your Skill solves real problems rather than documenting imagined ones.
726 
727**Evaluation-driven development:**
728 
7291. **Identify gaps**: Run Claude on representative tasks without a Skill. Document specific failures or missing context
7302. **Create evaluations**: Build three scenarios that test these gaps
7313. **Establish baseline**: Measure Claude's performance without the Skill
7324. **Write minimal instructions**: Create just enough content to address the gaps and pass evaluations
7335. **Iterate**: Execute evaluations, compare against baseline, and refine
734 
735This approach ensures you're solving actual problems rather than anticipating requirements that may never materialize.
736 
737**Evaluation structure**:
738 
739```json  theme={null}
740{
741  "skills": ["pdf-processing"],
742  "query": "Extract all text from this PDF file and save it to output.txt",
743  "files": ["test-files/document.pdf"],
744  "expected_behavior": [
745    "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
746    "Extracts text content from all pages in the document without missing any pages",
747    "Saves the extracted text to a file named output.txt in a clear, readable format"
748  ]
749}
750```
751 
752<Note>
753  This example demonstrates a data-driven evaluation with a simple testing rubric. We do not currently provide a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness.
754</Note>
755 
756### Develop Skills iteratively with Claude
757 
758The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that will be used by other instances ("Claude B"). Claude A helps you design and refine instructions, while Claude B tests them in real tasks. This works because Claude models understand both how to write effective agent instructions and what information agents need.
759 
760**Creating a new Skill:**
761 
7621. **Complete a task without a Skill**: Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.
763 
7642. **Identify the reusable pattern**: After completing the task, identify what context you provided that would be useful for similar future tasks.
765 
766   **Example**: If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (like "always exclude test accounts"), and common query patterns.
767 
7683. **Ask Claude A to create a Skill**: "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts."
769 
770   <Tip>
771     Claude models understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Simply ask Claude to create a Skill and it will generate properly structured SKILL.md content with appropriate frontmatter and body content.
772   </Tip>
773 
7744. **Review for conciseness**: Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that."
775 
7765. **Improve information architecture**: Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later."
777 
7786. **Test on similar tasks**: Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully.
779 
7807. **Iterate based on observation**: If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?"
781 
782**Iterating on existing Skills:**
783 
784The same hierarchical pattern continues when improving Skills. You alternate between:
785 
786* **Working with Claude A** (the expert who helps refine the Skill)
787* **Testing with Claude B** (the agent using the Skill to perform real work)
788* **Observing Claude B's behavior** and bringing insights back to Claude A
789 
7901. **Use the Skill in real workflows**: Give Claude B (with the Skill loaded) actual tasks, not test scenarios
791 
7922. **Observe Claude B's behavior**: Note where it struggles, succeeds, or makes unexpected choices
793 
794   **Example observation**: "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule."
795 
7963. **Return to Claude A for improvements**: Share the current SKILL.md and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?"
797 
7984. **Review Claude A's suggestions**: Claude A might suggest reorganizing to make rules more prominent, using stronger language like "MUST filter" instead of "always filter", or restructuring the workflow section.
799 
8005. **Apply and test changes**: Update the Skill with Claude A's refinements, then test again with Claude B on similar requests
801 
8026. **Repeat based on usage**: Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions.
803 
804**Gathering team feedback:**
805 
8061. Share Skills with teammates and observe their usage
8072. Ask: Does the Skill activate when expected? Are instructions clear? What's missing?
8083. Incorporate feedback to address blind spots in your own usage patterns
809 
810**Why this approach works**: Claude A understands agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.
811 
812### Observe how Claude navigates Skills
813 
814As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:
815 
816* **Unexpected exploration paths**: Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
817* **Missed connections**: Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent
818* **Overreliance on certain sections**: If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
819* **Ignored content**: If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions
820 
821Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Claude uses these when deciding whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.
822 
823## Anti-patterns to avoid
824 
825### Avoid Windows-style paths
826 
827Always use forward slashes in file paths, even on Windows:
828 
829* ✓ **Good**: `scripts/helper.py`, `reference/guide.md`
830* ✗ **Avoid**: `scripts\helper.py`, `reference\guide.md`
831 
832Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems.
833 
834### Avoid offering too many options
835 
836Don't present multiple approaches unless necessary:
837 
838````markdown  theme={null}
839**Bad example: Too many choices** (confusing):
840"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."
841 
842**Good example: Provide a default** (with escape hatch):
843"Use pdfplumber for text extraction:
844```python
845import pdfplumber
846```
847 
848For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
849````
850 
851## Advanced: Skills with executable code
852 
853The sections below focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to [Checklist for effective Skills](#checklist-for-effective-skills).
854 
855### Solve, don't punt
856 
857When writing scripts for Skills, handle error conditions rather than punting to Claude.
858 
859**Good example: Handle errors explicitly**:
860 
861```python  theme={null}
862def process_file(path):
863    """Process a file, creating it if it doesn't exist."""
864    try:
865        with open(path) as f:
866            return f.read()
867    except FileNotFoundError:
868        # Create file with default content instead of failing
869        print(f"File {path} not found, creating default")
870        with open(path, 'w') as f:
871            f.write('')
872        return ''
873    except PermissionError:
874        # Provide alternative instead of failing
875        print(f"Cannot access {path}, using default")
876        return ''
877```
878 
879**Bad example: Punt to Claude**:
880 
881```python  theme={null}
882def process_file(path):
883    # Just fail and let Claude figure it out
884    return open(path).read()
885```
886 
887Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it?
888 
889**Good example: Self-documenting**:
890 
891```python  theme={null}
892# HTTP requests typically complete within 30 seconds
893# Longer timeout accounts for slow connections
894REQUEST_TIMEOUT = 30
895 
896# Three retries balances reliability vs speed
897# Most intermittent failures resolve by the second retry
898MAX_RETRIES = 3
899```
900 
901**Bad example: Magic numbers**:
902 
903```python  theme={null}
904TIMEOUT = 47  # Why 47?
905RETRIES = 5   # Why 5?
906```
907 
908### Provide utility scripts
909 
910Even if Claude could write a script, pre-made scripts offer advantages:
911 
912**Benefits of utility scripts**:
913 
914* More reliable than generated code
915* Save tokens (no need to include code in context)
916* Save time (no code generation required)
917* Ensure consistency across uses
918 
919<img src="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=4bbc45f2c2e0bee9f2f0d5da669bad00" alt="Bundling executable scripts alongside instruction files" data-og-width="2048" width="2048" data-og-height="1154" height="1154" data-path="images/agent-skills-executable-scripts.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=280&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=9a04e6535a8467bfeea492e517de389f 280w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=560&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=e49333ad90141af17c0d7651cca7216b 560w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=840&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=954265a5df52223d6572b6214168c428 840w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1100&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=2ff7a2d8f2a83ee8af132b29f10150fd 1100w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=1650&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=48ab96245e04077f4d15e9170e081cfb 1650w, https://mintcdn.com/anthropic-claude-docs/4Bny2bjzuGBK7o00/images/agent-skills-executable-scripts.png?w=2500&fit=max&auto=format&n=4Bny2bjzuGBK7o00&q=85&s=0301a6c8b3ee879497cc5b5483177c90 2500w" />
920 
921The diagram above shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context.
922 
923**Important distinction**: Make clear in your instructions whether Claude should:
924 
925* **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
926* **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm"
927 
928For most utility scripts, execution is preferred because it's more reliable and efficient. See the [Runtime environment](#runtime-environment) section below for details on how script execution works.
929 
930**Example**:
931 
932````markdown  theme={null}
933## Utility scripts
934 
935**analyze_form.py**: Extract all form fields from PDF
936 
937```bash
938python scripts/analyze_form.py input.pdf > fields.json
939```
940 
941Output format:
942```json
943{
944  "field_name": {"type": "text", "x": 100, "y": 200},
945  "signature": {"type": "sig", "x": 150, "y": 500}
946}
947```
948 
949**validate_boxes.py**: Check for overlapping bounding boxes
950 
951```bash
952python scripts/validate_boxes.py fields.json
953# Returns: "OK" or lists conflicts
954```
955 
956**fill_form.py**: Apply field values to PDF
957 
958```bash
959python scripts/fill_form.py input.pdf fields.json output.pdf
960```
961````
962 
963### Use visual analysis
964 
965When inputs can be rendered as images, have Claude analyze them:
966 
967````markdown  theme={null}
968## Form layout analysis
969 
9701. Convert PDF to images:
971   ```bash
972   python scripts/pdf_to_images.py form.pdf
973   ```
974 
9752. Analyze each page image to identify form fields
9763. Claude can see field locations and types visually
977````
978 
979<Note>
980  In this example, you'd need to write the `pdf_to_images.py` script.
981</Note>
982 
983Claude's vision capabilities help understand layouts and structures.
984 
985### Create verifiable intermediate outputs
986 
987When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.
988 
989**Example**: Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.
990 
991**Solution**: Use the workflow pattern shown above (PDF form filling), but add an intermediate `changes.json` file that gets validated before applying changes. The workflow becomes: analyze → **create plan file** → **validate plan** → execute → verify.
992 
993**Why this pattern works:**
994 
995* **Catches errors early**: Validation finds problems before changes are applied
996* **Machine-verifiable**: Scripts provide objective verification
997* **Reversible planning**: Claude can iterate on the plan without touching originals
998* **Clear debugging**: Error messages point to specific problems
999 
1000**When to use**: Batch operations, destructive changes, complex validation rules, high-stakes operations.
1001 
1002**Implementation tip**: Make validation scripts verbose with specific error messages like "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" to help Claude fix issues.
1003 
1004### Package dependencies
1005 
1006Skills run in the code execution environment with platform-specific limitations:
1007 
1008* **claude.ai**: Can install packages from npm and PyPI and pull from GitHub repositories
1009* **Anthropic API**: Has no network access and no runtime package installation
1010 
1011List required packages in your SKILL.md and verify they're available in the [code execution tool documentation](/en/docs/agents-and-tools/tool-use/code-execution-tool).
1012 
1013### Runtime environment
1014 
1015Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see [The Skills architecture](/en/docs/agents-and-tools/agent-skills/overview#the-skills-architecture) in the overview.
1016 
1017**How this affects your authoring:**
1018 
1019**How Claude accesses Skills:**
1020 
10211. **Metadata pre-loaded**: At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt
10222. **Files read on-demand**: Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed
10233. **Scripts executed efficiently**: Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens
10244. **No context penalty for large files**: Reference files, data, or documentation don't consume context tokens until actually read
1025 
1026* **File paths matter**: Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes
1027* **Name files descriptively**: Use names that indicate content: `form_validation_rules.md`, not `doc2.md`
1028* **Organize for discovery**: Structure directories by domain or feature
1029  * Good: `reference/finance.md`, `reference/sales.md`
1030  * Bad: `docs/file1.md`, `docs/file2.md`
1031* **Bundle comprehensive resources**: Include complete API docs, extensive examples, large datasets; no context penalty until accessed
1032* **Prefer scripts for deterministic operations**: Write `validate_form.py` rather than asking Claude to generate validation code
1033* **Make execution intent clear**:
1034  * "Run `analyze_form.py` to extract fields" (execute)
1035  * "See `analyze_form.py` for the extraction algorithm" (read as reference)
1036* **Test file access patterns**: Verify Claude can navigate your directory structure by testing with real requests
1037 
1038**Example:**
1039 
1040```
1041bigquery-skill/
1042├── SKILL.md (overview, points to reference files)
1043└── reference/
1044    ├── finance.md (revenue metrics)
1045    ├── sales.md (pipeline data)
1046    └── product.md (usage analytics)
1047```
1048 
1049When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and invokes bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires.
1050 
1051For complete details on the technical architecture, see [How Skills work](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work) in the Skills overview.
1052 
1053### MCP tool references
1054 
1055If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.
1056 
1057**Format**: `ServerName:tool_name`
1058 
1059**Example**:
1060 
1061```markdown  theme={null}
1062Use the BigQuery:bigquery_schema tool to retrieve table schemas.
1063Use the GitHub:create_issue tool to create issues.
1064```
1065 
1066Where:
1067 
1068* `BigQuery` and `GitHub` are MCP server names
1069* `bigquery_schema` and `create_issue` are the tool names within those servers
1070 
1071Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
1072 
1073### Avoid assuming tools are installed
1074 
1075Don't assume packages are available:
1076 
1077````markdown  theme={null}
1078**Bad example: Assumes installation**:
1079"Use the pdf library to process the file."
1080 
1081**Good example: Explicit about dependencies**:
1082"Install required package: `pip install pypdf`
1083 
1084Then use it:
1085```python
1086from pypdf import PdfReader
1087reader = PdfReader("file.pdf")
1088```"
1089````
1090 
1091## Technical notes
1092 
1093### YAML frontmatter requirements
1094 
1095The SKILL.md frontmatter requires `name` (64 characters max) and `description` (1024 characters max) fields. See the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
1096 
1097### Token budgets
1098 
1099Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the [Skills overview](/en/docs/agents-and-tools/agent-skills/overview#how-skills-work).
1100 
1101## Checklist for effective Skills
1102 
1103Before sharing a Skill, verify:
1104 
1105### Core quality
1106 
1107* [ ] Description is specific and includes key terms
1108* [ ] Description includes both what the Skill does and when to use it
1109* [ ] SKILL.md body is under 500 lines
1110* [ ] Additional details are in separate files (if needed)
1111* [ ] No time-sensitive information (or in "old patterns" section)
1112* [ ] Consistent terminology throughout
1113* [ ] Examples are concrete, not abstract
1114* [ ] File references are one level deep
1115* [ ] Progressive disclosure used appropriately
1116* [ ] Workflows have clear steps
1117 
1118### Code and scripts
1119 
1120* [ ] Scripts solve problems rather than punt to Claude
1121* [ ] Error handling is explicit and helpful
1122* [ ] No "voodoo constants" (all values justified)
1123* [ ] Required packages listed in instructions and verified as available
1124* [ ] Scripts have clear documentation
1125* [ ] No Windows-style paths (all forward slashes)
1126* [ ] Validation/verification steps for critical operations
1127* [ ] Feedback loops included for quality-critical tasks
1128 
1129### Testing
1130 
1131* [ ] At least three evaluations created
1132* [ ] Tested with Haiku, Sonnet, and Opus
1133* [ ] Tested with real usage scenarios
1134* [ ] Team feedback incorporated (if applicable)
1135 
1136## Next steps
1137 
1138<CardGroup cols={2}>
1139  <Card title="Get started with Agent Skills" icon="rocket" href="/en/docs/agents-and-tools/agent-skills/quickstart">
1140    Create your first Skill
1141  </Card>
1142 
1143  <Card title="Use Skills in Claude Code" icon="terminal" href="/en/docs/claude-code/skills">
1144    Create and manage Skills in Claude Code
1145  </Card>
1146 
1147  <Card title="Use Skills with the API" icon="code" href="/en/api/skills-guide">
1148    Upload and use Skills programmatically
1149  </Card>
1150</CardGroup>
1151