Page history
PDF Processing
agents-and-tools/agent-skills/best-practices
History
agents-and-tools/agent-skills/best-practices Changed · +34 / -28 lines
from line 270
The complete Skill directory structure might look like this: -```text -pdf/ -├── SKILL.md # Main instructions (loaded when triggered) -├── FORMS.md # Form-filling guide (loaded as needed) -├── reference.md # API reference (loaded as needed) -├── examples.md # Usage examples (loaded as needed) -└── scripts/ - ├── analyze_form.py # Utility script (executed, not loaded) - ├── fill_form.py # Form filling script - └── validate.py # Validation script -``` +* `pdf/` + * `SKILL.md`: Main instructions (loaded when triggered) + + * `FORMS.md`: Form-filling guide (loaded as needed) + + * `reference.md`: API reference (loaded as needed) + + * `examples.md`: Usage examples (loaded as needed) + + * `scripts/` + + * `analyze_form.py`: Utility script (executed, not loaded) + * `fill_form.py`: Form filling script + * `validate.py`: Validation script + #### Pattern 1: High-level guide with references ````markdown
from line 318
For 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. -```text -bigquery-skill/ -├── SKILL.md (overview and navigation) -└── reference/ - ├── finance.md (revenue, billing metrics) - ├── sales.md (opportunities, pipeline) - ├── product.md (API usage, features) - └── marketing.md (campaigns, attribution) -``` +* `bigquery-skill/` + * `SKILL.md` (overview and navigation) + + * `reference/` + + * `finance.md` (revenue, billing metrics) + * `sales.md` (opportunities, pipeline) + * `product.md` (API usage, features) + * `marketing.md` (campaigns, attribution) + ````markdown SKILL.md # BigQuery Data Analysis
from line 1066
**Example:** -```text -bigquery-skill/ -├── SKILL.md (overview, points to reference files) -└── reference/ - ├── finance.md (revenue metrics) - ├── sales.md (pipeline data) - └── product.md (usage analytics) -``` +* `bigquery-skill/` + + * `SKILL.md` (overview, points to reference files) + + * `reference/` + + * `finance.md` (revenue metrics) + * `sales.md` (pipeline data) + * `product.md` (usage analytics) When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and calls 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.
agents-and-tools/agent-skills/best-practices First recorded · 1179 lines, first recorded
## Core principles ### Concise is key ### Set appropriate degrees of freedom ### Test with all models you plan to use ## Skill structure ### Naming conventions ### Writing effective descriptions ### Progressive disclosure patterns #### Visual overview: From simple to complex #### Pattern 1: High-level guide with references #### Pattern 2: Domain-specific organization #### Pattern 3: Conditional details ### Avoid deeply nested references ### Structure longer reference files with table of contents ## Workflows and feedback loops ### Use workflows for complex tasks ### Implement feedback loops ## Content guidelines ### Avoid time-sensitive information ### Use consistent terminology ## Common patterns ### Template pattern # [Analysis Title] ## Executive summary ## Key findings ## Recommendations # [Analysis Title] ## Executive summary ## Key findings ## Recommendations ### Examples pattern ### Conditional workflow pattern ## Evaluation and iteration ### Build evaluations first ### Develop Skills iteratively with Claude ### Observe how Claude navigates Skills ## Anti-patterns to avoid ### Avoid Windows-style paths ### Avoid offering too many options ## Advanced: Skills with executable code ### Solve, don't defer ### Provide utility scripts # Returns: "OK" or lists conflicts ### Use visual analysis ### Create verifiable intermediate outputs ### Package dependencies ### Runtime environment ### MCP tool references ### Avoid assuming tools are installed ## Technical notes ### YAML frontmatter requirements ### Token budgets ## Checklist for effective Skills ### Core quality ### Code and scripts ### Testing ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Skill authoring best practices
url: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
description: Learn how to write effective Skills that Claude can discover and use successfully.
---
Good 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.
For conceptual background on how Skills work, see the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
## Core principles
### Concise is key
The [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:
* The system prompt
* Conversation history
* Other Skills' metadata
* Your actual request
Not 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.
**Default assumption:** Claude is already very smart
Only add context Claude doesn't already have. Challenge each piece of information:
* "Does Claude really need this explanation?"
* "Can I assume Claude knows this?"
* "Does this paragraph justify its token cost?"
**Good example: Concise** (approximately 50 tokens):
````markdown
## Extract PDF text
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
````
**Bad example: Too verbose** (approximately 150 tokens):
```markdown
## Extract PDF text
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...
```
The concise version assumes Claude already has information about PDFs and how libraries work.
### Set appropriate degrees of freedom
Match the level of specificity to the task's fragility and variability.
**High freedom** (text-based instructions):
Use when:
* Multiple approaches are valid
* Decisions depend on context
* Heuristics guide the approach
Example:
```markdown
## Code review process
1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions
```
**Medium freedom** (pseudocode or scripts with parameters):
Use when:
* A preferred pattern exists
* Some variation is acceptable
* Configuration affects behavior
Example:
````markdown
## Generate report
Use this template and customize as needed:
```python
def generate_report(data, format="markdown", include_charts=True):
# Process data
# Generate output in specified format
# Optionally include visualizations
```
````
**Low freedom** (specific scripts, few or no parameters):
Use when:
* Operations are fragile and error-prone
* Consistency is critical
* A specific sequence must be followed
Example:
````markdown
## Database migration
Run exactly this script:
```bash
python scripts/migrate.py --verify --backup
```
Do not modify the command or add additional flags.
````
**Analogy:** Think of Claude as a robot exploring a path:
* **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.
* **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.
### Test with all models you plan to use
Skills 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.
**Testing considerations by model:**
* **Claude Haiku** (fast, economical): Does the Skill provide enough guidance?
* **Claude Sonnet** (balanced): Is the Skill clear and efficient?
* **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining?
What 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.
## Skill structure
<Note>
**YAML Frontmatter:** The SKILL.md frontmatter requires two fields:
`name`:
* Maximum 64 characters
* Must contain only lowercase letters, numbers, and hyphens
* Cannot contain XML tags
* Cannot contain reserved words: "anthropic", "claude"
`description`:
* Must be non-empty
* Maximum 1,024 characters
* Cannot contain XML tags
* Should describe what the Skill does and when to use it
For complete Skill structure details, see the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#skill-structure).
</Note>
### Naming conventions
Use consistent naming patterns to make Skills easier to reference and discuss. Consider using **gerund form** (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.
Remember that the `name` field must use lowercase letters, numbers, and hyphens only.
**Good naming examples (gerund form):**
* `processing-pdfs`
* `analyzing-spreadsheets`
* `managing-databases`
* `testing-code`
* `writing-documentation`
**Acceptable alternatives:**
* Noun phrases: `pdf-processing`, `spreadsheet-analysis`
* Action-oriented: `process-pdfs`, `analyze-spreadsheets`
**Avoid:**
* Vague names: `helper`, `utils`, `tools`
* Overly generic: `documents`, `data`, `files`
* Reserved words: `anthropic-helper`, `claude-tools`
* Inconsistent patterns within your skill collection
Consistent naming makes it easier to:
* Reference Skills in documentation and conversations
* Understand what a Skill does at a glance
* Organize and search through multiple Skills
* Maintain a professional, cohesive skill library
### Writing effective descriptions
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
<Warning>
**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
* **Good:** "Processes Excel files and generates reports"
* **Avoid:** "I can help you process Excel files"
* **Avoid:** "You can use this to process Excel files"
</Warning>
**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.
Each 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.
Effective examples:
**PDF Processing skill:**
```yaml
description: 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.
```
**Excel Analysis skill:**
```yaml
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
```
**Git Commit Helper skill:**
```yaml
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
```
Avoid vague descriptions like these:
```yaml
description: Helps with documents
```
```yaml
description: Processes data
```
```yaml
description: Does stuff with files
```
### Progressive disclosure patterns
SKILL.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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the overview.
**Practical guidance:**
* Keep SKILL.md body under 500 lines for optimal performance
* Split content into separate files when approaching this limit
* Use the following patterns to organize instructions, code, and resources effectively
#### Visual overview: From simple to complex
A basic Skill starts with just a SKILL.md file containing metadata and instructions:
As your Skill grows, you can bundle additional content that Claude loads only when needed:
The complete Skill directory structure might look like this:
```text
pdf/
├── SKILL.md # Main instructions (loaded when triggered)
├── FORMS.md # Form-filling guide (loaded as needed)
├── reference.md # API reference (loaded as needed)
├── examples.md # Usage examples (loaded as needed)
└── scripts/
├── analyze_form.py # Utility script (executed, not loaded)
├── fill_form.py # Form filling script
└── validate.py # Validation script
```
#### Pattern 1: High-level guide with references
````markdown
---
name: pdf-processing
description: 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.
---
# PDF Processing
## Quick start
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
Cut at 300 lines.