Agent Skills Best Practices Reference

Agent Skills Best Practices Reference

Source: Anthropic's Official Skill Authoring Best Practices

This reference consolidates best practices for authoring effective Agent Skills. For the latest guidance, visit the official documentation.

Core Principles

Context Efficiency

Not every token in your Skill has an immediate cost:

• At startup: Only metadata (name and description) from all Skills is pre-loaded
• On activation: Claude reads SKILL.md only when the Skill becomes relevant
• On demand: Additional files are read only as needed

However, once Claude loads SKILL.md, every token competes with conversation history and other context. Being concise still matters.

Test with All Models You Plan to Use

Skills act as additions to models, so effectiveness depends on the underlying model:

What works for Opus might need more detail for Haiku. Aim for instructions that work well with all models you plan to support.

Skill Structure

Naming Conventions

Use gerund form (verb + -ing) for Skill names to clearly describe the activity:

Good naming examples:

• "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"
• Inconsistent patterns within your skill collection

Writing Effective Descriptions

The description field enables Skill discovery and should include:

1. What the Skill does
2. When to use it (triggers/contexts)

Critical Rules:

1. Always write in third person - The description is injected into the system prompt

   • ✅ Good: "Processes Excel files and generates reports"
   • ❌ Avoid: "I can help you process Excel files"
   • ❌ Avoid: "You can use this to process Excel files"

2. Be specific and include key terms - Claude uses the description to choose from potentially 100+ available Skills

Effective examples:

# PDF Processing skill
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.

# Git Commit Helper skill
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:

# Bad
description: Helps with documents
description: Processes data
description: Does stuff with files

Progressive Disclosure Patterns

SKILL.md serves as an overview that points Claude to detailed materials as needed.

Key Guidelines

• Keep SKILL.md body under 500 lines for optimal performance
• Split content into separate files when approaching this limit
• Use reference files for detailed documentation

Pattern 1: High-Level Guide with References

---
name: PDF Processing
description: Extracts text and tables from PDF files...
---

# 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:

bigquery-skill/ ├── SKILL.md (overview and navigation) └── reference/ ├── finance.md (revenue, billing metrics) ├── sales.md (opportunities, pipeline) └── product.md (API usage, features)

This ensures Claude only loads relevant domain content.

### Pattern 3: Conditional Details

Show basic content, link to advanced content:

```markdown
# DOCX Processing

## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)

Avoid Deeply Nested References

Claude may only partially read files referenced from other referenced files.

Bad (too deep):

SKILL.md → advanced.md → details.md → actual information

Good (one level deep):

SKILL.md → advanced.md
         → reference.md
         → examples.md

Structure Longer Reference Files

For reference files longer than 100 lines, include a table of contents:

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns

## Authentication and setup
...

Workflows and Feedback Loops

Use Workflows for Complex Tasks

Break complex operations into clear, sequential steps. Provide a checklist Claude can track:

## Research synthesis workflow

Copy this checklist and track your progress:

Research Progress:

• Step 1: Read all source documents
• Step 2: Identify key themes
• Step 3: Cross-reference claims
• Step 4: Create structured summary
• Step 5: Verify citations

**Step 1: Read all source documents**
Review each document in the `sources/` directory...

Implement Feedback Loops

Common pattern: Run validator → fix errors → repeat

## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python scripts/validate.py`
3. If validation fails:
   - Review the error message
   - Fix the issues
   - Run validation again
4. **Only proceed when validation passes**

Content Guidelines

Avoid Time-Sensitive Information

Bad (will become wrong):

If you're doing this before August 2025, use the old API.

Good (use "old patterns" section):

## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
</details>

Use Consistent Terminology

Choose one term and use it throughout:

Good (consistent):

• Always "API endpoint"
• Always "field"
• Always "extract"

Bad (inconsistent):

• Mix "API endpoint", "URL", "route", "path"
• Mix "field", "box", "element", "control"

Common Patterns

Template Pattern

Provide templates for output format:

## Report structure

ALWAYS use this exact template structure:

```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation

### Examples Pattern

Provide input/output pairs:

```markdown
## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:

fix(reports): correct date formatting in timezone conversion

Conditional Workflow Pattern

Guide through decision points:

## Document modification workflow

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change

Evaluation and Iteration

Build Evaluations First

Create evaluations BEFORE writing extensive documentation.

Evaluation-driven development:

1. Identify gaps: Run Claude on tasks without a Skill. Document failures
2. Create evaluations: Build 3+ scenarios that test these gaps
3. Establish baseline: Measure performance without the Skill
4. Write minimal instructions: Just enough to address gaps
5. Iterate: Execute evaluations, compare, refine

Develop Skills Iteratively with Claude

Work with one Claude instance ("Claude A") to create a Skill for other instances ("Claude B"):

1. Complete a task without a Skill: Work through a problem, notice what context you repeatedly provide
2. Identify reusable patterns: What information would help similar future tasks?
3. Ask Claude A to create a Skill: "Create a Skill that captures this pattern"
4. Review for conciseness: Remove unnecessary explanations
5. Test with Claude B: Use the Skill on related tasks
6. Iterate based on observation: Refine based on Claude B's behavior

Anti-Patterns to Avoid

❌ Windows-Style Paths

Always use forward slashes:

• ✅ scripts/helper.py
• ❌ scripts\helper.py

❌ Too Many Options

Don't present multiple approaches unless necessary:

Bad:

You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image...

Good:

Use pdfplumber for text extraction:
```python
import pdfplumber

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.

### ❌ Vague Descriptions
Avoid descriptions that don't help Claude select the skill.

### ❌ Over-Explaining
Don't repeat general knowledge. Claude already knows standard programming concepts.

---

## Checklist for Effective Skills

### Metadata
- [ ] Name uses gerund form (verb + -ing) or is consistently styled
- [ ] Name is lowercase, max 64 chars, no consecutive hyphens
- [ ] Description explains what AND when to use (max 1024 chars)
- [ ] Description is written in third person
- [ ] Description includes relevant keywords for discovery

### Content
- [ ] SKILL.md is under 500 lines
- [ ] Instructions are clear and actionable
- [ ] Complex workflows have checklists
- [ ] Reference files are organized by domain
- [ ] References are one level deep (not nested)
- [ ] Longer reference files have table of contents

### Quality
- [ ] No time-sensitive information
- [ ] Consistent terminology throughout
- [ ] Tested with all target models
- [ ] Includes examples where helpful
- [ ] Validation/feedback loops for complex tasks

---

## Additional Resources

- **Official Best Practices**: [platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- **Specification**: See [agentskills-specification.md](agentskills-specification.md)
- **Example Skills**: [github.com/anthropics/skills](https://github.com/anthropics/skills)