skillshubskillshub

Best Practices

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.

Core principles

Concise is key

The context window 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, ~50 tokens):

## 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, ~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 we recommend pdfplumber because it's easy to use and handles most cases well...

The concise version assumes Claude knows what PDFs are 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

Medium freedom (pseudocode or scripts with parameters):

Use when:

  • A preferred pattern exists
  • Some variation is acceptable
  • Configuration affects behavior

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

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.

Skill structure

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 1024 characters
  • Cannot contain XML tags
  • Should describe what the Skill does and when to use it

Naming conventions

Use consistent naming patterns to make Skills easier to reference and discuss. We recommend using gerund form (verb + -ing) for Skill names.

Good naming examples (gerund form):

  • processing-pdfs
  • analyzing-spreadsheets
  • managing-databases
  • testing-code
  • writing-documentation

Avoid:

  • Vague names: helper, utils, tools
  • Overly generic: documents, data, files
  • Reserved words: anthropic-helper, claude-tools

Writing effective descriptions

The description field enables Skill discovery and should include both what the Skill does and when to use it.

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"

Effective examples:

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.
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx 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.

Practical guidance:

  • Keep SKILL.md body under 500 lines for optimal performance
  • Split content into separate files when approaching this limit
  • Use the patterns below to organize instructions, code, and resources effectively

Pattern 1: High-level guide with references

---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents.
---

# PDF Processing

## Quick start
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

Advanced features

Form filling: See FORMS.md for complete guide API reference: See REFERENCE.md for all methods


**Pattern 2**: Domain-specific organization

For Skills with multiple domains, organize content by domain to avoid loading irrelevant context.

**Pattern 3**: Conditional details

Show basic content, link to advanced content.

### Avoid deeply nested references

Claude may partially read files when they're referenced from other referenced files. Keep references one level deep from SKILL.md.

## Workflows and feedback loops

### Use workflows for complex tasks

Break 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.

### Implement feedback loops

Common pattern: Run validator → fix errors → repeat

This pattern greatly improves output quality.

## Content guidelines

### Avoid time-sensitive information

Don't include information that will become outdated.

### Use consistent terminology

Choose one term and use it throughout the Skill:

**Good - Consistent**:
- Always "API endpoint"
- Always "field"
- Always "extract"

**Bad - Inconsistent**:
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"

## Common patterns

### Template pattern

Provide templates for output format. Match the level of strictness to your needs.

### Examples pattern

For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting.

### Conditional workflow pattern

Guide Claude through decision points.

## Evaluation and iteration

### Build evaluations first

Create evaluations BEFORE writing extensive documentation. This ensures your Skill solves real problems rather than documenting imagined ones.

### Develop Skills iteratively with Claude

The 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").

### Observe how Claude navigates Skills

As you iterate on Skills, pay attention to how Claude actually uses them in practice.

## Anti-patterns to avoid

### Avoid Windows-style paths

Always use forward slashes in file paths, even on Windows:
- ✓ Good: `scripts/helper.py`, `reference/guide.md`
- ✗ Avoid: `scripts\helper.py`, `reference\guide.md`

### Avoid offering too many options

Don't present multiple approaches unless necessary. Provide a default with an escape hatch.

## Advanced: Skills with executable code

### Solve, don't punt

When writing scripts for Skills, handle error conditions rather than punting to Claude.

### Provide utility scripts

Even if Claude could write a script, pre-made scripts offer advantages:
- More reliable than generated code
- Save tokens (no need to include code in context)
- Save time (no code generation required)
- Ensure consistency across uses

### Use visual analysis

When inputs can be rendered as images, have Claude analyze them.

### Create verifiable intermediate outputs

When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early.

### Package dependencies

Skills run in the code execution environment with platform-specific limitations.

## Technical notes

### YAML frontmatter requirements

- `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words
- `description`: Maximum 1024 characters, non-empty, no XML tags

### Token budgets

Keep SKILL.md body under 500 lines for optimal performance.

## Checklist for effective Skills

Before sharing a Skill, verify:

### Core quality
- ✓ Description is specific and includes key terms
- ✓ Description includes both what the Skill does and when to use it
- ✓ SKILL.md body is under 500 lines
- ✓ Additional details are in separate files (if needed)
- ✓ No time-sensitive information
- ✓ Consistent terminology throughout
- ✓ Examples are concrete, not abstract
- ✓ File references are one level deep
- ✓ Progressive disclosure used appropriately
- ✓ Workflows have clear steps

### Code and scripts
- ✓ Scripts solve problems rather than punt to Claude
- ✓ Error handling is explicit and helpful
- ✓ No "voodoo constants" (all values justified)
- ✓ Required packages listed and verified
- ✓ No Windows-style paths

### Testing
- ✓ At least three evaluations created
- ✓ Tested with Haiku, Sonnet, and Opus
- ✓ Tested with real usage scenarios

Quickstart

Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.

Using Skills with the API

Learn how to use Agent Skills to extend Claude's capabilities through the API.

On this page

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
Advanced features