1---
2name: agent-skills-format
3description: Official documentation for the Agent Skills format - a lightweight, open standard for extending AI agent capabilities with specialized knowledge and workflows.
4doc_type: reference
5source_url: No
6---
7 
8Overview
9 
10Copy page
11 
12A simple, open format for giving agents new capabilities and expertise.
13 
14Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently.
15​
16Why Agent Skills?
17Agents are increasingly capable, but often don’t have the context they need to do real work reliably. Skills solve this by giving agents access to procedural knowledge and company-, team-, and user-specific context they can load on demand. Agents with access to a set of skills can extend their capabilities based on the task they’re working on.
18For skill authors: Build capabilities once and deploy them across multiple agent products.
19For compatible agents: Support for skills lets end users give agents new capabilities out of the box.
20For teams and enterprises: Capture organizational knowledge in portable, version-controlled packages.
21​
22What can Agent Skills enable?
23Domain expertise: Package specialized knowledge into reusable instructions, from legal review processes to data analysis pipelines.
24New capabilities: Give agents new capabilities (e.g. creating presentations, building MCP servers, analyzing datasets).
25Repeatable workflows: Turn multi-step tasks into consistent and auditable workflows.
26Interoperability: Reuse the same skill across different skills-compatible agent products.
27​
28Adoption
29Agent Skills are supported by leading AI development tools.
30OpenCode
31Cursor
32Amp
33Letta
34Goose
35GitHub
36VS Code
37Claude Code
38Claude
39OpenAI Codex
40​
41Open development
42The Agent Skills format was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products. The standard is open to contributions from the broader ecosystem.
43 
44What are skills?
45 
46Copy page
47 
48Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.
49 
50At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.
51my-skill/
52├── SKILL.md          # Required: instructions + metadata
53├── scripts/          # Optional: executable code
54├── references/       # Optional: documentation
55└── assets/           # Optional: templates, resources
56​
57How skills work
58Skills use progressive disclosure to manage context efficiently:
59Discovery: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.
60Activation: When a task matches a skill’s description, the agent reads the full SKILL.md instructions into context.
61Execution: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed.
62This approach keeps agents fast while giving them access to more context on demand.
63​
64The SKILL.md file
65Every skill starts with a SKILL.md file containing YAML frontmatter and Markdown instructions:
66---
67name: pdf-processing
68description: Extract text and tables from PDF files, fill forms, merge documents.
69---
70 
71# PDF Processing
72 
73## When to use this skill
74Use this skill when the user needs to work with PDF files...
75 
76## How to extract text
771. Use pdfplumber for text extraction...
78 
79## How to fill forms
80...
81The following frontmatter is required at the top of SKILL.md:
82name: A short identifier
83description: When to use this skill
84The Markdown body contains the actual instructions and has no specific restrictions on structure or content.
85This simple format has some key advantages:
86Self-documenting: A skill author or user can read a SKILL.md and understand what it does, making skills easy to audit and improve.
87Extensible: Skills can range in complexity from just text instructions to executable code, assets, and templates.
88Portable: Skills are just files, so they’re easy to edit, version, and share.
89​
90Next steps
91View the specification to understand the full format.
92Add skills support to your agent to build a compatible client.
93See example skills on GitHub.
94Read authoring best practices for writing effective skills.
95Use the reference library to validate skills and generate prompt XML.
96 
97Specification
98 
99Copy page
100 
101The complete format specification for Agent Skills.
102 
103This document defines the Agent Skills format.
104​
105Directory structure
106A skill is a directory containing at minimum a SKILL.md file:
107skill-name/
108└── SKILL.md          # Required
109You can optionally include additional directories such as scripts/, references/, and assets/ to support your skill.
110​
111SKILL.md format
112The SKILL.md file must contain YAML frontmatter followed by Markdown content.
113​
114Frontmatter (required)
115---
116name: skill-name
117description: A description of what this skill does and when to use it.
118---
119With optional fields:
120---
121name: pdf-processing
122description: Extract text and tables from PDF files, fill forms, merge documents.
123license: Apache-2.0
124metadata:
125  author: example-org
126  version: "1.0"
127---
128Field	Required	Constraints
129name	Yes	Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.
130description	Yes	Max 1024 characters. Non-empty. Describes what the skill does and when to use it.
131license	No	License name or reference to a bundled license file.
132compatibility	No	Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
133metadata	No	Arbitrary key-value mapping for additional metadata.
134allowed-tools	No	Space-delimited list of pre-approved tools the skill may use. (Experimental)
135​
136name field
137The required name field:
138Must be 1-64 characters
139May only contain unicode lowercase alphanumeric characters and hyphens (a-z and -)
140Must not start or end with -
141Must not contain consecutive hyphens (--)
142Must match the parent directory name
143Valid examples:
144name: pdf-processing
145name: data-analysis
146name: code-review
147Invalid examples:
148name: PDF-Processing  # uppercase not allowed
149name: -pdf  # cannot start with hyphen
150name: pdf--processing  # consecutive hyphens not allowed
151​
152description field
153The required description field:
154Must be 1-1024 characters
155Should describe both what the skill does and when to use it
156Should include specific keywords that help agents identify relevant tasks
157Good example:
158description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
159Poor example:
160description: Helps with PDFs.
161​
162license field
163The optional license field:
164Specifies the license applied to the skill
165We recommend keeping it short (either the name of a license or the name of a bundled license file)
166Example:
167license: Proprietary. LICENSE.txt has complete terms
168​
169compatibility field
170The optional compatibility field:
171Must be 1-500 characters if provided
172Should only be included if your skill has specific environment requirements
173Can indicate intended product, required system packages, network access needs, etc.
174Examples:
175compatibility: Designed for Claude Code (or similar products)
176compatibility: Requires git, docker, jq, and access to the internet
177Most skills do not need the compatibility field.
178​
179metadata field
180The optional metadata field:
181A map from string keys to string values
182Clients can use this to store additional properties not defined by the Agent Skills spec
183We recommend making your key names reasonably unique to avoid accidental conflicts
184Example:
185metadata:
186  author: example-org
187  version: "1.0"
188​
189allowed-tools field
190The optional allowed-tools field:
191A space-delimited list of tools that are pre-approved to run
192Experimental. Support for this field may vary between agent implementations
193Example:
194allowed-tools: Bash(git:*) Bash(jq:*) Read
195​
196Body content
197The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
198Recommended sections:
199Step-by-step instructions
200Examples of inputs and outputs
201Common edge cases
202Note that the agent will load this entire file once it’s decided to activate a skill. Consider splitting longer SKILL.md content into referenced files.
203​
204Optional directories
205​
206scripts/
207Contains executable code that agents can run. Scripts should:
208Be self-contained or clearly document dependencies
209Include helpful error messages
210Handle edge cases gracefully
211Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.
212​
213references/
214Contains additional documentation that agents can read when needed:
215REFERENCE.md - Detailed technical reference
216FORMS.md - Form templates or structured data formats
217Domain-specific files (finance.md, legal.md, etc.)
218Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context.
219​
220assets/
221Contains static resources:
222Templates (document templates, configuration templates)
223Images (diagrams, examples)
224Data files (lookup tables, schemas)
225​
226Progressive disclosure
227Skills should be structured for efficient use of context:
228Metadata (~100 tokens): The name and description fields are loaded at startup for all skills
229Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated
230Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required
231Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files.
232​
233File references
234When referencing other files in your skill, use relative paths from the skill root:
235See [the reference guide](references/REFERENCE.md) for details.
236 
237Run the extraction script:
238scripts/extract.py
239Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.
240​
241Validation
242Use the skills-ref reference library to validate your skills:
243skills-ref validate ./my-skill
244This checks that your SKILL.md frontmatter is valid and follows all naming conventions.
245 
246Integrate skills into your agent
247 
248Copy page
249 
250How to add Agent Skills support to your agent or tool.
251 
252This guide explains how to add skills support to an AI agent or development tool.
253​
254Integration approaches
255The two main approaches to integrating skills are:
256Filesystem-based agents operate within a computer environment (bash/unix) and represent the most capable option. Skills are activated when models issue shell commands like cat /path/to/my-skill/SKILL.md. Bundled resources are accessed through shell commands.
257Tool-based agents function without a dedicated computer environment. Instead, they implement tools allowing models to trigger skills and access bundled assets. The specific tool implementation is up to the developer.
258​
259Overview
260A skills-compatible agent needs to:
261Discover skills in configured directories
262Load metadata (name and description) at startup
263Match user tasks to relevant skills
264Activate skills by loading full instructions
265Execute scripts and access resources as needed
266​
267Skill discovery
268Skills are folders containing a SKILL.md file. Your agent should scan configured directories for valid skills.
269​
270Loading metadata
271At startup, parse only the frontmatter of each SKILL.md file. This keeps initial context usage low.
272​
273Parsing frontmatter
274function parseMetadata(skillPath):
275    content = readFile(skillPath + "/SKILL.md")
276    frontmatter = extractYAMLFrontmatter(content)
277 
278    return {
279        name: frontmatter.name,
280        description: frontmatter.description,
281        path: skillPath
282    }
283​
284Injecting into context
285Include skill metadata in the system prompt so the model knows what skills are available.
286Follow your platform’s guidance for system prompt updates. For example, for Claude models, the recommended format uses XML:
287<available_skills>
288  <skill>
289    <name>pdf-processing</name>
290    <description>Extracts text and tables from PDF files, fills forms, merges documents.</description>
291    <location>/path/to/skills/pdf-processing/SKILL.md</location>
292  </skill>
293  <skill>
294    <name>data-analysis</name>
295    <description>Analyzes datasets, generates charts, and creates summary reports.</description>
296    <location>/path/to/skills/data-analysis/SKILL.md</location>
297  </skill>
298</available_skills>
299For filesystem-based agents, include the location field with the absolute path to the SKILL.md file. For tool-based agents, the location can be omitted.
300Keep metadata concise. Each skill should add roughly 50-100 tokens to the context.
301​
302Security considerations
303Script execution introduces security risks. Consider:
304Sandboxing: Run scripts in isolated environments
305Allowlisting: Only execute scripts from trusted skills
306Confirmation: Ask users before running potentially dangerous operations
307Logging: Record all script executions for auditing
308​
309Reference implementation
310The skills-ref library provides Python utilities and a CLI for working with skills.
311For example:
312Validate a skill directory:
313skills-ref validate <path>
314Generate <available_skills> XML for agent prompts:
315skills-ref to-prompt <path>...
316Use the library source code as a reference implementation.
317 
318Skill authoring best practices
319 
320Copy page
321 
322Learn how to write effective Skills that Claude can discover and use successfully.
323Good 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.
324 
325For conceptual background on how Skills work, see the Skills overview.
326 
327Core principles
328Concise is key
329The context window is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
330 
331The system prompt
332Conversation history
333Other Skills' metadata
334Your actual request
335Not 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.
336 
337Default assumption: Claude is already very smart
338 
339Only add context Claude doesn't already have. Challenge each piece of information:
340 
341"Does Claude really need this explanation?"
342"Can I assume Claude knows this?"
343"Does this paragraph justify its token cost?"
344Good example: Concise (approximately 50 tokens):
345 
346## Extract PDF text
347 
348Use pdfplumber for text extraction:
349 
350```python
351import pdfplumber
352 
353with pdfplumber.open("file.pdf") as pdf:
354    text = pdf.pages[0].extract_text()
355```
356Bad example: Too verbose (approximately 150 tokens):
357 
358## Extract PDF text
359 
360PDF (Portable Document Format) files are a common file format that contains
361text, images, and other content. To extract text from a PDF, you'll need to
362use a library. There are many libraries available for PDF processing, but we
363recommend pdfplumber because it's easy to use and handles most cases well.
364First, you'll need to install it using pip. Then you can use the code below...
365The concise version assumes Claude knows what PDFs are and how libraries work.
366 
367Set appropriate degrees of freedom
368Match the level of specificity to the task's fragility and variability.
369 
370High freedom (text-based instructions):
371 
372Use when:
373 
374Multiple approaches are valid
375Decisions depend on context
376Heuristics guide the approach
377Example:
378 
379## Code review process
380 
3811. Analyze the code structure and organization
3822. Check for potential bugs or edge cases
3833. Suggest improvements for readability and maintainability
3844. Verify adherence to project conventions
385Medium freedom (pseudocode or scripts with parameters):
386 
387Use when:
388 
389A preferred pattern exists
390Some variation is acceptable
391Configuration affects behavior
392Example:
393 
394## Generate report
395 
396Use this template and customize as needed:
397 
398```python
399def generate_report(data, format="markdown", include_charts=True):
400    # Process data
401    # Generate output in specified format
402    # Optionally include visualizations
403```
404Low freedom (specific scripts, few or no parameters):
405 
406Use when:
407 
408Operations are fragile and error-prone
409Consistency is critical
410A specific sequence must be followed
411Example:
412 
413## Database migration
414 
415Run exactly this script:
416 
417```bash
418python scripts/migrate.py --verify --backup
419```
420 
421Do not modify the command or add additional flags.
422Analogy: Think of Claude as a robot exploring a path:
423 
424Narrow 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.
425Open 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.
426Test with all models you plan to use
427Skills 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.
428 
429Testing considerations by model:
430 
431Claude Haiku (fast, economical): Does the Skill provide enough guidance?
432Claude Sonnet (balanced): Is the Skill clear and efficient?
433Claude Opus (powerful reasoning): Does the Skill avoid over-explaining?
434What 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.
435 
436Skill structure
437YAML Frontmatter: The SKILL.md frontmatter requires two fields:
438 
439name:
440 
441Maximum 64 characters
442Must contain only lowercase letters, numbers, and hyphens
443Cannot contain XML tags
444Cannot contain reserved words: "anthropic", "claude"
445description:
446 
447Must be non-empty
448Maximum 1024 characters
449Cannot contain XML tags
450Should describe what the Skill does and when to use it
451For complete Skill structure details, see the Skills overview.
452 
453Naming conventions
454Use 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.
455 
456Remember that the name field must use lowercase letters, numbers, and hyphens only.
457 
458Good naming examples (gerund form):
459 
460processing-pdfs
461analyzing-spreadsheets
462managing-databases
463testing-code
464writing-documentation
465Acceptable alternatives:
466 
467Noun phrases: pdf-processing, spreadsheet-analysis
468Action-oriented: process-pdfs, analyze-spreadsheets
469Avoid:
470 
471Vague names: helper, utils, tools
472Overly generic: documents, data, files
473Reserved words: anthropic-helper, claude-tools
474Inconsistent patterns within your skill collection
475Consistent naming makes it easier to:
476 
477Reference Skills in documentation and conversations
478Understand what a Skill does at a glance
479Organize and search through multiple Skills
480Maintain a professional, cohesive skill library
481Writing effective descriptions
482The description field enables Skill discovery and should include both what the Skill does and when to use it.
483 
484Always write in third person. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
485 
486Good: "Processes Excel files and generates reports"
487Avoid: "I can help you process Excel files"
488Avoid: "You can use this to process Excel files"
489Be specific and include key terms. Include both what the Skill does and specific triggers/contexts for when to use it.
490 
491Each 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.
492 
493Effective examples:
494 
495PDF Processing skill:
496 
497description: 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.
498Excel Analysis skill:
499 
500description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
501Git Commit Helper skill:
502 
503description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
504Avoid vague descriptions like these:
505 
506description: Helps with documents
507description: Processes data
508description: Does stuff with files
509Progressive disclosure patterns
510SKILL.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 in the overview.
511 
512Practical guidance:
513 
514Keep SKILL.md body under 500 lines for optimal performance
515Split content into separate files when approaching this limit
516Use the patterns below to organize instructions, code, and resources effectively
517Visual overview: From simple to complex
518A basic Skill starts with just a SKILL.md file containing metadata and instructions:
519 
520Simple SKILL.md file showing YAML frontmatter and markdown body
521 
522As your Skill grows, you can bundle additional content that Claude loads only when needed:
523 
524Bundling additional reference files like reference.md and forms.md.
525 
526The complete Skill directory structure might look like this:
527 
528pdf/
529├── SKILL.md              # Main instructions (loaded when triggered)
530├── FORMS.md              # Form-filling guide (loaded as needed)
531├── reference.md          # API reference (loaded as needed)
532├── examples.md           # Usage examples (loaded as needed)
533└── scripts/
534    ├── analyze_form.py   # Utility script (executed, not loaded)
535    ├── fill_form.py      # Form filling script
536    └── validate.py       # Validation script
537Pattern 1: High-level guide with references
538---
539name: pdf-processing
540description: 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.
541---
542 
543# PDF Processing
544 
545## Quick start
546 
547Extract text with pdfplumber:
548```python
549import pdfplumber
550with pdfplumber.open("file.pdf") as pdf:
551    text = pdf.pages[0].extract_text()
552```
553 
554## Advanced features
555 
556**Form filling**: See [FORMS.md](FORMS.md) for complete guide
557**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
558**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
559Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
560 
561Pattern 2: Domain-specific organization
562For 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.
563 
564bigquery-skill/
565├── SKILL.md (overview and navigation)
566└── reference/
567    ├── finance.md (revenue, billing metrics)
568    ├── sales.md (opportunities, pipeline)
569    ├── product.md (API usage, features)
570    └── marketing.md (campaigns, attribution)
571SKILL.md
572# BigQuery Data Analysis
573 
574## Available datasets
575 
576**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
577**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
578**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
579**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
580 
581## Quick search
582 
583Find specific metrics using grep:
584 
585```bash
586grep -i "revenue" reference/finance.md
587grep -i "pipeline" reference/sales.md
588grep -i "api usage" reference/product.md
589```
590Pattern 3: Conditional details
591Show basic content, link to advanced content:
592 
593# DOCX Processing
594 
595## Creating documents
596 
597Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
598 
599## Editing documents
600 
601For simple edits, modify the XML directly.
602 
603**For tracked changes**: See [REDLINING.md](REDLINING.md)
604**For OOXML details**: See [OOXML.md](OOXML.md)
605Claude reads REDLINING.md or OOXML.md only when the user needs those features.
606 
607Avoid deeply nested references
608Claude 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.
609 
610Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed.
611 
612Bad example: Too deep:
613 
614# SKILL.md
615See [advanced.md](advanced.md)...
616 
617# advanced.md
618See [details.md](details.md)...
619 
620# details.md
621Here's the actual information...
622Good example: One level deep:
623 
624# SKILL.md
625 
626**Basic usage**: [instructions in SKILL.md]
627**Advanced features**: See [advanced.md](advanced.md)
628**API reference**: See [reference.md](reference.md)
629**Examples**: See [examples.md](examples.md)
630Structure longer reference files with table of contents
631For 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.
632 
633Example:
634 
635# API Reference
636 
637## Contents
638- Authentication and setup
639- Core methods (create, read, update, delete)
640- Advanced features (batch operations, webhooks)
641- Error handling patterns
642- Code examples
643 
644## Authentication and setup
645...
646 
647## Core methods
648...
649Claude can then read the complete file or jump to specific sections as needed.
650 
651For details on how this filesystem-based architecture enables progressive disclosure, see the Runtime environment section in the Advanced section below.
652 
653Workflows and feedback loops
654Use workflows for complex tasks
655Break 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.
656 
657Example 1: Research synthesis workflow (for Skills without code):
658 
659## Research synthesis workflow
660 
661Copy this checklist and track your progress:
662 
663```
664Research Progress:
665- [ ] Step 1: Read all source documents
666- [ ] Step 2: Identify key themes
667- [ ] Step 3: Cross-reference claims
668- [ ] Step 4: Create structured summary
669- [ ] Step 5: Verify citations
670```
671 
672**Step 1: Read all source documents**
673 
674Review each document in the `sources/` directory. Note the main arguments and supporting evidence.
675 
676**Step 2: Identify key themes**
677 
678Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?
679 
680**Step 3: Cross-reference claims**
681 
682For each major claim, verify it appears in the source material. Note which source supports each point.
683 
684**Step 4: Create structured summary**
685 
686Organize findings by theme. Include:
687- Main claim
688- Supporting evidence from sources
689- Conflicting viewpoints (if any)
690 
691**Step 5: Verify citations**
692 
693Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
694This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multi-step process.
695 
696Example 2: PDF form filling workflow (for Skills with code):
697 
698## PDF form filling workflow
699 
700Copy this checklist and check off items as you complete them:
701 
702```
703Task Progress:
704- [ ] Step 1: Analyze the form (run analyze_form.py)
705- [ ] Step 2: Create field mapping (edit fields.json)
706- [ ] Step 3: Validate mapping (run validate_fields.py)
707- [ ] Step 4: Fill the form (run fill_form.py)
708- [ ] Step 5: Verify output (run verify_output.py)
709```
710 
711**Step 1: Analyze the form**
712 
713Run: `python scripts/analyze_form.py input.pdf`
714 
715This extracts form fields and their locations, saving to `fields.json`.
716 
717**Step 2: Create field mapping**
718 
719Edit `fields.json` to add values for each field.
720 
721**Step 3: Validate mapping**
722 
723Run: `python scripts/validate_fields.py fields.json`
724 
725Fix any validation errors before continuing.
726 
727**Step 4: Fill the form**
728 
729Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
730 
731**Step 5: Verify output**
732 
733Run: `python scripts/verify_output.py output.pdf`
734 
735If verification fails, return to Step 2.
736Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multi-step workflows.
737 
738Implement feedback loops
739Common pattern: Run validator → fix errors → repeat
740 
741This pattern greatly improves output quality.
742 
743Example 1: Style guide compliance (for Skills without code):
744 
745## Content review process
746 
7471. Draft your content following the guidelines in STYLE_GUIDE.md
7482. Review against the checklist:
749   - Check terminology consistency
750   - Verify examples follow the standard format
751   - Confirm all required sections are present
7523. If issues found:
753   - Note each issue with specific section reference
754   - Revise the content
755   - Review the checklist again
7564. Only proceed when all requirements are met
7575. Finalize and save the document
758This 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.
759 
760Example 2: Document editing process (for Skills with code):
761 
762## Document editing process
763 
7641. Make your edits to `word/document.xml`
7652. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
7663. If validation fails:
767   - Review the error message carefully
768   - Fix the issues in the XML
769   - Run validation again
7704. **Only proceed when validation passes**
7715. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
7726. Test the output document
773The validation loop catches errors early.
774 
775Content guidelines
776Avoid time-sensitive information
777Don't include information that will become outdated:
778 
779Bad example: Time-sensitive (will become wrong):
780 
781If you're doing this before August 2025, use the old API.
782After August 2025, use the new API.
783Good example (use "old patterns" section):
784 
785## Current method
786 
787Use the v2 API endpoint: `api.example.com/v2/messages`
788 
789## Old patterns
790 
791<details>
792<summary>Legacy v1 API (deprecated 2025-08)</summary>
793 
794The v1 API used: `api.example.com/v1/messages`
795 
796This endpoint is no longer supported.
797</details>
798The old patterns section provides historical context without cluttering the main content.
799 
800Use consistent terminology
801Choose one term and use it throughout the Skill:
802 
803Good - Consistent:
804 
805Always "API endpoint"
806Always "field"
807Always "extract"
808Bad - Inconsistent:
809 
810Mix "API endpoint", "URL", "API route", "path"
811Mix "field", "box", "element", "control"
812Mix "extract", "pull", "get", "retrieve"
813Consistency helps Claude understand and follow instructions.
814 
815Common patterns
816Template pattern
817Provide templates for output format. Match the level of strictness to your needs.
818 
819For strict requirements (like API responses or data formats):
820 
821## Report structure
822 
823ALWAYS use this exact template structure:
824 
825```markdown
826# [Analysis Title]
827 
828## Executive summary
829[One-paragraph overview of key findings]
830 
831## Key findings
832- Finding 1 with supporting data
833- Finding 2 with supporting data
834- Finding 3 with supporting data
835 
836## Recommendations
8371. Specific actionable recommendation
8382. Specific actionable recommendation
839```
840For flexible guidance (when adaptation is useful):
841 
842## Report structure
843 
844Here is a sensible default format, but use your best judgment based on the analysis:
845 
846```markdown
847# [Analysis Title]
848 
849## Executive summary
850[Overview]
851 
852## Key findings
853[Adapt sections based on what you discover]
854 
855## Recommendations
856[Tailor to the specific context]
857```
858 
859Adjust sections as needed for the specific analysis type.
860Examples pattern
861For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting:
862 
863## Commit message format
864 
865Generate commit messages following these examples:
866 
867**Example 1:**
868Input: Added user authentication with JWT tokens
869Output:
870```
871feat(auth): implement JWT-based authentication
872 
873Add login endpoint and token validation middleware
874```
875 
876**Example 2:**
877Input: Fixed bug where dates displayed incorrectly in reports
878Output:
879```
880fix(reports): correct date formatting in timezone conversion
881 
882Use UTC timestamps consistently across report generation
883```
884 
885**Example 3:**
886Input: Updated dependencies and refactored error handling
887Output:
888```
889chore: update dependencies and refactor error handling
890 
891- Upgrade lodash to 4.17.21
892- Standardize error response format across endpoints
893```
894 
895Follow this style: type(scope): brief description, then detailed explanation.
896Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
897 
898Conditional workflow pattern
899Guide Claude through decision points:
900 
901## Document modification workflow
902 
9031. Determine the modification type:
904 
905   **Creating new content?** → Follow "Creation workflow" below
906   **Editing existing content?** → Follow "Editing workflow" below
907 
9082. Creation workflow:
909   - Use docx-js library
910   - Build document from scratch
911   - Export to .docx format
912 
9133. Editing workflow:
914   - Unpack existing document
915   - Modify XML directly
916   - Validate after each change
917   - Repack when complete
918If 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.
919 
920Evaluation and iteration
921Build evaluations first
922Create evaluations BEFORE writing extensive documentation. This ensures your Skill solves real problems rather than documenting imagined ones.
923 
924Evaluation-driven development:
925 
926Identify gaps: Run Claude on representative tasks without a Skill. Document specific failures or missing context
927Create evaluations: Build three scenarios that test these gaps
928Establish baseline: Measure Claude's performance without the Skill
929Write minimal instructions: Create just enough content to address the gaps and pass evaluations
930Iterate: Execute evaluations, compare against baseline, and refine
931This approach ensures you're solving actual problems rather than anticipating requirements that may never materialize.
932 
933Evaluation structure:
934 
935{
936  "skills": ["pdf-processing"],
937  "query": "Extract all text from this PDF file and save it to output.txt",
938  "files": ["test-files/document.pdf"],
939  "expected_behavior": [
940    "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
941    "Extracts text content from all pages in the document without missing any pages",
942    "Saves the extracted text to a file named output.txt in a clear, readable format"
943  ]
944}
945This 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.
946 
947Develop Skills iteratively with Claude
948The 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.
949 
950Creating a new Skill:
951 
952Complete 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.
953 
954Identify the reusable pattern: After completing the task, identify what context you provided that would be useful for similar future tasks.
955 
956Example: 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.
957 
958Ask 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."
959 
960Claude 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.
961 
962Review for conciseness: Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that."
963 
964Improve 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."
965 
966Test 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.
967 
968Iterate 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?"
969 
970Iterating on existing Skills:
971 
972The same hierarchical pattern continues when improving Skills. You alternate between:
973 
974Working with Claude A (the expert who helps refine the Skill)
975Testing with Claude B (the agent using the Skill to perform real work)
976Observing Claude B's behavior and bringing insights back to Claude A
977Use the Skill in real workflows: Give Claude B (with the Skill loaded) actual tasks, not test scenarios
978 
979Observe Claude B's behavior: Note where it struggles, succeeds, or makes unexpected choices
980 
981Example 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."
982 
983Return 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?"
984 
985Review 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.
986 
987Apply and test changes: Update the Skill with Claude A's refinements, then test again with Claude B on similar requests
988 
989Repeat 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.
990 
991Gathering team feedback:
992 
993Share Skills with teammates and observe their usage
994Ask: Does the Skill activate when expected? Are instructions clear? What's missing?
995Incorporate feedback to address blind spots in your own usage patterns
996Why 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.
997 
998Observe how Claude navigates Skills
999As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:
1000 
1001Unexpected 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
1002Missed connections: Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent
1003Overreliance on certain sections: If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
1004Ignored content: If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions
1005Iterate 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.
1006 
1007Anti-patterns to avoid
1008Avoid Windows-style paths
1009Always use forward slashes in file paths, even on Windows:
1010 
1011✓ Good: scripts/helper.py, reference/guide.md
1012✗ Avoid: scripts\helper.py, reference\guide.md
1013Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems.
1014 
1015Avoid offering too many options
1016Don't present multiple approaches unless necessary:
1017 
1018**Bad example: Too many choices** (confusing):
1019"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."
1020 
1021**Good example: Provide a default** (with escape hatch):
1022"Use pdfplumber for text extraction:
1023```python
1024import pdfplumber
1025```
1026 
1027For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
1028Advanced: Skills with executable code
1029The sections below focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to Checklist for effective Skills.
1030 
1031Solve, don't punt
1032When writing scripts for Skills, handle error conditions rather than punting to Claude.
1033 
1034Good example: Handle errors explicitly:
1035 
1036def process_file(path):
1037    """Process a file, creating it if it doesn't exist."""
1038    try:
1039        with open(path) as f:
1040            return f.read()
1041    except FileNotFoundError:
1042        # Create file with default content instead of failing
1043        print(f"File {path} not found, creating default")
1044        with open(path, 'w') as f:
1045            f.write('')
1046        return ''
1047    except PermissionError:
1048        # Provide alternative instead of failing
1049        print(f"Cannot access {path}, using default")
1050        return ''
1051Bad example: Punt to Claude:
1052 
1053def process_file(path):
1054    # Just fail and let Claude figure it out
1055    return open(path).read()
1056Configuration 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?
1057 
1058Good example: Self-documenting:
1059 
1060# HTTP requests typically complete within 30 seconds
1061# Longer timeout accounts for slow connections
1062REQUEST_TIMEOUT = 30
1063 
1064# Three retries balances reliability vs speed
1065# Most intermittent failures resolve by the second retry
1066MAX_RETRIES = 3
1067Bad example: Magic numbers:
1068 
1069TIMEOUT = 47  # Why 47?
1070RETRIES = 5   # Why 5?
1071Provide utility scripts
1072Even if Claude could write a script, pre-made scripts offer advantages:
1073 
1074Benefits of utility scripts:
1075 
1076More reliable than generated code
1077Save tokens (no need to include code in context)
1078Save time (no code generation required)
1079Ensure consistency across uses
1080Bundling executable scripts alongside instruction files
1081 
1082The 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.
1083 
1084Important distinction: Make clear in your instructions whether Claude should:
1085 
1086Execute the script (most common): "Run analyze_form.py to extract fields"
1087Read it as reference (for complex logic): "See analyze_form.py for the field extraction algorithm"
1088For most utility scripts, execution is preferred because it's more reliable and efficient. See the Runtime environment section below for details on how script execution works.
1089 
1090Example:
1091 
1092## Utility scripts
1093 
1094**analyze_form.py**: Extract all form fields from PDF
1095 
1096```bash
1097python scripts/analyze_form.py input.pdf > fields.json
1098```
1099 
1100Output format:
1101```json
1102{
1103  "field_name": {"type": "text", "x": 100, "y": 200},
1104  "signature": {"type": "sig", "x": 150, "y": 500}
1105}
1106```
1107 
1108**validate_boxes.py**: Check for overlapping bounding boxes
1109 
1110```bash
1111python scripts/validate_boxes.py fields.json
1112# Returns: "OK" or lists conflicts
1113```
1114 
1115**fill_form.py**: Apply field values to PDF
1116 
1117```bash
1118python scripts/fill_form.py input.pdf fields.json output.pdf
1119```
1120Use visual analysis
1121When inputs can be rendered as images, have Claude analyze them:
1122 
1123## Form layout analysis
1124 
11251. Convert PDF to images:
1126   ```bash
1127   python scripts/pdf_to_images.py form.pdf
1128   ```
1129 
11302. Analyze each page image to identify form fields
11313. Claude can see field locations and types visually
1132In this example, you'd need to write the pdf_to_images.py script.
1133 
1134Claude's vision capabilities help understand layouts and structures.
1135 
1136Create verifiable intermediate outputs
1137When 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.
1138 
1139Example: 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.
1140 
1141Solution: 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.
1142 
1143Why this pattern works:
1144 
1145Catches errors early: Validation finds problems before changes are applied
1146Machine-verifiable: Scripts provide objective verification
1147Reversible planning: Claude can iterate on the plan without touching originals
1148Clear debugging: Error messages point to specific problems
1149When to use: Batch operations, destructive changes, complex validation rules, high-stakes operations.
1150 
1151Implementation 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.
1152 
1153Package dependencies
1154Skills run in the code execution environment with platform-specific limitations:
1155 
1156claude.ai: Can install packages from npm and PyPI and pull from GitHub repositories
1157Anthropic API: Has no network access and no runtime package installation
1158List required packages in your SKILL.md and verify they're available in the code execution tool documentation.
1159 
1160Runtime environment
1161Skills 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 in the overview.
1162 
1163How this affects your authoring:
1164 
1165How Claude accesses Skills:
1166 
1167Metadata pre-loaded: At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt
1168Files read on-demand: Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed
1169Scripts executed efficiently: Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens
1170No context penalty for large files: Reference files, data, or documentation don't consume context tokens until actually read
1171File paths matter: Claude navigates your skill directory like a filesystem. Use forward slashes (reference/guide.md), not backslashes
1172Name files descriptively: Use names that indicate content: form_validation_rules.md, not doc2.md
1173Organize for discovery: Structure directories by domain or feature
1174Good: reference/finance.md, reference/sales.md
1175Bad: docs/file1.md, docs/file2.md
1176Bundle comprehensive resources: Include complete API docs, extensive examples, large datasets; no context penalty until accessed
1177Prefer scripts for deterministic operations: Write validate_form.py rather than asking Claude to generate validation code
1178Make execution intent clear:
1179"Run analyze_form.py to extract fields" (execute)
1180"See analyze_form.py for the extraction algorithm" (read as reference)
1181Test file access patterns: Verify Claude can navigate your directory structure by testing with real requests
1182Example:
1183 
1184bigquery-skill/
1185├── SKILL.md (overview, points to reference files)
1186└── reference/
1187    ├── finance.md (revenue metrics)
1188    ├── sales.md (pipeline data)
1189    └── product.md (usage analytics)
1190When 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.
1191 
1192For complete details on the technical architecture, see How Skills work in the Skills overview.
1193 
1194MCP tool references
1195If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.
1196 
1197Format: ServerName:tool_name
1198 
1199Example:
1200 
1201Use the BigQuery:bigquery_schema tool to retrieve table schemas.
1202Use the GitHub:create_issue tool to create issues.
1203Where:
1204 
1205BigQuery and GitHub are MCP server names
1206bigquery_schema and create_issue are the tool names within those servers
1207Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
1208 
1209Avoid assuming tools are installed
1210Don't assume packages are available:
1211 
1212**Bad example: Assumes installation**:
1213"Use the pdf library to process the file."
1214 
1215**Good example: Explicit about dependencies**:
1216"Install required package: `pip install pypdf`
1217 
1218Then use it:
1219```python
1220from pypdf import PdfReader
1221reader = PdfReader("file.pdf")
1222```"
1223Technical notes
1224YAML frontmatter requirements
1225The SKILL.md frontmatter requires name and description fields with specific validation rules:
1226 
1227name: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words
1228description: Maximum 1024 characters, non-empty, no XML tags
1229See the Skills overview for complete structure details.
1230 
1231Token budgets
1232Keep 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.
1233 
1234Checklist for effective Skills
1235Before sharing a Skill, verify:
1236 
1237Core quality
1238 Description is specific and includes key terms
1239 Description includes both what the Skill does and when to use it
1240 SKILL.md body is under 500 lines
1241 Additional details are in separate files (if needed)
1242 No time-sensitive information (or in "old patterns" section)
1243 Consistent terminology throughout
1244 Examples are concrete, not abstract
1245 File references are one level deep
1246 Progressive disclosure used appropriately
1247 Workflows have clear steps
1248Code and scripts
1249 Scripts solve problems rather than punt to Claude
1250 Error handling is explicit and helpful
1251 No "voodoo constants" (all values justified)
1252 Required packages listed in instructions and verified as available
1253 Scripts have clear documentation
1254 No Windows-style paths (all forward slashes)
1255 Validation/verification steps for critical operations
1256 Feedback loops included for quality-critical tasks
1257Testing
1258 At least three evaluations created
1259 Tested with Haiku, Sonnet, and Opus
1260 Tested with real usage scenarios
1261 Team feedback incorporated (if applicable)
1262 
1263 
1264 https://github.com/anthropics/skills