skills-best-practices

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:

| Level | When Loaded | Token Cost | Content | |-------|------------|------------|---------| | 1: Metadata | Always (startup) | ~100 tokens | name + description from frontmatter | | 2: Instructions | When skill triggers | <5k tokens | SKILL.md body | | 3: Resources | As needed | Effectively unlimited | Bundled files, scripts |

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

## Advanced features
Form filling: See FORMS.md
API reference: See 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

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

| Field | Rules | |-------|-------| | name | Kebab-case, max 64 chars, lowercase + numbers + hyphens only. No "claude" or "anthropic" | | description | Non-empty, max 1024 chars, no XML tags. WHAT + WHEN |

Optional Fields (Claude Code)

| Field | Purpose | |-------|---------| | argument-hint | Autocomplete hint, e.g. [issue-number] | | disable-model-invocation | true = only user can invoke (for deploy, commit) | | user-invocable | false = hidden from / menu (background knowledge) | | allowed-tools | Tools allowed without permission, e.g. Read, Grep, Glob | | model | Override model for this skill | | effort | Override effort level: low, medium, high, max | | context | fork = run in isolated subagent | | agent | Subagent type when context: fork (e.g. Explore, Plan) | | paths | Glob patterns limiting when skill activates |

Naming Conventions

Prefer gerund form for clarity:

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:

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

Set Degrees of Freedom

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. Avoid nested chains:

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

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 this checklist and track progress:
[ ] Step 1: Analyze input
[ ] Step 2: Create plan
[ ] Step 3: Validate plan
[ ] Step 4: Execute
[ ] Step 5: Verify output

More patterns in references/patterns.md.

Scripts

When your skill includes executable code:

Testing

Triggering Tests

Should trigger:
"Help me set up a new project in [Service]"
"I need to create a project" (paraphrased)
Should NOT trigger:
"What's the weather?" (unrelated)
"Write Python code" (too generic)

Functional Tests

Test normal operations, edge cases, and out-of-scope requests. Run the same request 3-5 times to check consistency.

Debug Triggering

Ask Claude: "When would you use the [skill-name] skill?" - it quotes the description back. Adjust based on what's missing.

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | Skill never loads | Description too vague | Add specific triggers and key terms | | Skill loads for wrong tasks | Description too broad | Add negative triggers, be more specific | | Instructions not followed | Too verbose or buried | Put critical instructions at top, use headers | | Slow/degraded responses | SKILL.md too large | Move content to references/, keep under 500 lines | | "Could not find SKILL.md" | Wrong filename | Must be exactly SKILL.md (case-sensitive) | | "Invalid skill name" | Spaces or capitals | Use kebab-case: my-skill-name |

Distribution

| Surface | How to Deploy | |---------|--------------| | Claude.ai | Settings > Features > Upload zip | | Claude Code (personal) | ~/.claude/skills//SKILL.md | | Claude Code (project) | .claude/skills//SKILL.md | | Claude Code (plugin) | /skills//SKILL.md | | API | POST /v1/skills with beta headers | | Enterprise | Managed settings (org-wide) |

Skills don't sync across surfaces - deploy separately to each.

Security

Additional References

Official Resources

[Concrete input/output pairs]

[Common errors and fixes]

Reference Files
Keep references one level deep from SKILL.md. Avoid nested chains:

BAD: Too deep

GOOD: One level

For reference files >100 lines, include a table of contents at the top.

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.