Authoring Effective Agent Skills: Best Practices Guide

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 create Skills that deliver results.

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:

• The system prompt
• Conversation history
• Other Skills' metadata
• Your actual request

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 vs. Bad Examples

Good example: Concise (approximately 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()

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

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

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

Analogy: Think of Claude as a robot exploring a path:

• Narrow bridge with cliffs: Provide specific guardrails (low freedom)
• Open field: Give general direction (high freedom)

Skill Structure

YAML Frontmatter Requirements

Every Skill requires a SKILL.md file with YAML frontmatter:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

Required fields: name and description

Field requirements:

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. We recommend gerund form (verb + -ing):

Good examples:

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

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

Be specific and include key terms. Include both what the Skill does and specific triggers/contexts for when to use it.

Effective examples:

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

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

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, 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. 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:
    text = pdf.pages[0].extract_text()

Advanced features

Form filling: See FORMS.md for complete guide API reference: See REFERENCE.md for all methods Examples: See EXAMPLES.md for common patterns

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)

Avoid Deeply Nested References

Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.

Bad example: Too deep:

# SKILL.md
See [advanced.md](advanced.md)...

# advanced.md
See [details.md](details.md)...

# details.md
Here's the actual information...

Good example: One level deep:

# SKILL.md

**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.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.

Example: Research synthesis workflow

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

Implement Feedback Loops

Common pattern: Run validator → fix errors → repeat. This pattern greatly improves output quality.

Example: Style guide compliance

## Content review process

1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
   - Check terminology consistency
   - Verify examples follow the standard format
   - Confirm all required sections are present
3. If issues found:
   - Note each issue with specific section reference
   - Revise the content
   - Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document

Content Guidelines

Avoid Time-sensitive Information

Don't include information that will become outdated:

Bad example: Time-sensitive:

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

Good example:

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

This endpoint is no longer supported.
</details>

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"
• Mix "extract", "pull", "get", "retrieve"

Common Patterns

Template Pattern

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

For strict requirements:

## 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
- Finding 3 with supporting data

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

Adjust sections as needed for the specific analysis type.

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation

chore: update dependencies and refactor error handling

• Upgrade lodash to 4.17.21
• Standardize error response format across endpoints

Conditional Workflow Pattern

Guide Claude 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
   - Export to .docx format

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

Advanced: Skills with Executable Code

Solve, Don't Punt

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

Good example: Handle errors explicitly:

def process_file(path):
    """Process a file, creating it if it doesn't exist."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Create file with default content instead of failing
        print(f"File {path} not found, creating default")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # Provide alternative instead of failing
        print(f"Cannot access {path}, using default")
        return ''

Bad example: Punt to Claude:

def process_file(path):
    # Just fail and let Claude figure it out
    return open(path).read()

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

Important distinction: Make clear in your instructions whether Claude should:

• Execute the script (most common): "Run analyze_form.py to extract fields"
• Read it as reference (for complex logic): "See analyze_form.py for the field extraction algorithm"

Create Verifiable Intermediate Outputs

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

Why this pattern works:

• Catches errors early: Validation finds problems before changes are applied
• Machine-verifiable: Scripts provide objective verification
• Reversible planning: Claude can iterate on the plan without touching originals
• Clear debugging: Error messages point to specific problems

When to use: Batch operations, destructive changes, complex validation rules, high-stakes operations.

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:

Bad example: Too many choices: "You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

Good example: Provide a default: "Use pdfplumber for text extraction:

import pdfplumber

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

Checklist for Effective Skills

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 (or in "old patterns" section)
• 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 in instructions and verified as available
• Scripts have clear documentation
• No Windows-style paths (all forward slashes)
• Validation/verification steps for critical operations
• Feedback loops included for quality-critical tasks

Testing

• At least three evaluations created
• Tested with Haiku, Sonnet, and Opus
• Tested with real usage scenarios
• Team feedback incorporated (if applicable)

Next Steps

Ready to create your own Skill? Start with:

1. Identify a use case: What repetitive task could benefit from automation?
2. Write minimal instructions: Start small and iterate
3. Test with real scenarios: Ensure the Skill solves actual problems
4. Refine based on feedback: Continuously improve through iteration

Master the art of Skill authoring and unlock the full potential of Claude's capabilities.