Skills Best Practices

Comprehensive reference for building Agent Skills that follow Anthropic's official guidelines. Skills are folders containing instructions, scripts, and resources that teach Claude how to handle specific tasks. They follow the Agent Skills open standard.

Quick Start

A minimal skill is a directory with a SKILL.md file:

my-skill/
├── SKILL.md          # Required - instructions with YAML frontmatter
├── references/       # Optional - detailed docs loaded on demand
├── scripts/          # Optional - executable code
└── assets/           # Optional - templates, fonts, icons

Minimal SKILL.md:

---
name: my-skill-name
description: What it does. Use when [specific triggers].
---

# My Skill Name

[Instructions here]

Only name and description are required in frontmatter.

Core Design Principles

Progressive Disclosure (Most Important)

Skills load information in three levels to minimize token usage:

Keep SKILL.md under 500 lines. Move detailed docs to separate files and reference them:

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [reference.md](reference.md)

Claude reads referenced files only when the task requires them.

Composability

Skills work alongside other skills. Don't assume yours is the only one loaded.

Portability

Skills work across Claude.ai, Claude Code, API, and Agent SDK without modification (if dependencies are available).

Writing the Description (Critical)

The description is the single most important field - it determines when your skill activates. Claude uses it to decide relevance from potentially 100+ available skills.

Rules

• Write in third person ("Processes files..." not "I help you process files...")
• Include WHAT it does + WHEN to use it
• Max 1024 characters, no XML angle brackets
• Be slightly "pushy" - Claude tends to undertrigger rather than overtrigger
• Include specific trigger phrases users would naturally say

Good vs Bad

# GOOD - specific, actionable, includes triggers
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.

# BAD - too vague
description: Helps with documents.

# BAD - missing triggers
description: Creates sophisticated multi-page documentation systems.

More examples in references/description-guide.md.

Frontmatter Reference

Required Fields

The agentskills.io standard and the Claude API require both fields. Claude Code is more lenient: name falls back to the directory name, and description falls back to the first markdown paragraph. Write both anyway for portability.

Optional Fields (Claude Code)

Naming Conventions

The name (and its folder) must: be 1-64 chars; use only lowercase letters, numbers, and hyphens; not start or end with a hyphen; not contain consecutive hyphens (--); and match the parent directory name. Anthropic surfaces also reject the reserved words claude and anthropic.

Prefer gerund form for clarity:

• processing-pdfs, analyzing-spreadsheets, managing-databases
• Also acceptable: pdf-processing, process-pdfs
• Avoid: helper, utils, tools, documents

Structuring Instructions

Be Concise

Claude is smart. Only add context it doesn't already have:

# GOOD (~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 (~150 tokens)

Extract PDF text

PDF files are a common file format containing text and images. To extract text, you need a library. There are many available...

### Avoid Too Many Options

Don't present multiple approaches unless necessary. Give one default with an escape hatch:

```markdown
# BAD: "Use pypdf, or pdfplumber, or PyMuPDF, or pdf2image..."
# GOOD: "Use pdfplumber for text extraction. For scanned PDFs needing
#        OCR, use pdf2image with pytesseract instead."

Set Degrees of Freedom

• High freedom (text guidelines): Multiple approaches valid, context-dependent
• Medium freedom (pseudocode/templates): Preferred pattern exists, some variation OK
• Low freedom (exact scripts): Operations are fragile, consistency critical

Recommended SKILL.md Structure

# Skill Name

## Quick start
[Minimal working example]

## Workflow Decision Tree
[Route to the right approach based on task type]

## Detailed Instructions
[Step-by-step for each workflow]

## Examples
[Concrete input/output pairs]

## Troubleshooting
[Common errors and fixes]

Reference Files

Keep references one level deep from SKILL.md. "Depth" means the reference chain (a file linking to a file linking to a file), not filesystem nesting - a references/ subdirectory is fine. In a chain, Claude may preview files with partial reads (head) and miss content.

# BAD: Too deep
SKILL.md -> advanced.md -> details.md -> actual info

# GOOD: One level
SKILL.md -> advanced.md (contains the info directly)
SKILL.md -> reference.md (contains the info directly)

For reference files >100 lines, include a table of contents at the top. Watch file size too: a single reference of many hundreds of lines defeats progressive disclosure even at one level deep, because Claude loads the whole file for any subtopic. Split large references by subtopic so each task pulls only what it needs.

Patterns

Sequential Workflow

## Step 1: Analyze input
Run: `python scripts/analyze.py input.pdf`

## Step 2: Validate
Run: `python scripts/validate.py fields.json`
Fix any errors before continuing.

## Step 3: Execute
Run: `python scripts/process.py input.pdf fields.json output.pdf`

Conditional Workflow (Decision Tree)

## Workflow Decision Tree
**Creating new content?** -> Follow "Creation workflow"
**Editing existing content?** -> Follow "Editing workflow"
**Reviewing content?** -> Follow "Review workflow"

Feedback Loop

1. Make edits
2. Validate: `python scripts/validate.py`
3. If validation fails -> fix issues -> go to step 2
4. Only proceed when validation passes

Checklist Pattern (for complex tasks)

Copy