Skill authoring best practices — Claude Docs
by Anthropic (Claude Docs)
How to write Skills that Claude actually discovers and uses well.
Overview
This official guide is the definitive checklist for writing effective Skills. Its core principles: be concise because the context window is a shared public good; set appropriate degrees of freedom (high-freedom text instructions for open-ended tasks, low-freedom exact scripts for fragile ones); and test with every model you plan to use. It gives concrete guidance on naming (prefer gerund form like 'processing-pdfs'), writing descriptions in the third person that state both what the Skill does and when to use it, and structuring progressive disclosure (keep SKILL.md under 500 lines, keep file references one level deep, add a table of contents to long reference files). It covers workflow checklists, validator/fix feedback loops, avoiding time-sensitive information and Windows-style paths, and an evaluation-driven development loop: build evaluations first, establish a baseline without the Skill, write minimal instructions, then iterate. A notable pattern is developing Skills iteratively with two Claude instances ('Claude A' refines the Skill, 'Claude B' tests it), plus a final effectiveness checklist.
At a Glance
- Topic
- Skills
- Level
- Intermediate
- Format
- Guide
- Cost
- Free
- Duration
- ~25 min read
- Provider
- Anthropic (Claude Docs)
- Hands-on
- No
- Certificate
- None
What You’ll Learn
- ✓How to write descriptions that make a Skill discoverable and correctly triggered
- ✓Matching a task's 'degree of freedom' to instructions vs. exact scripts
- ✓Progressive-disclosure structuring rules (500-line limit, one-level references, TOCs)
- ✓Building evaluations first and iterating Skills against a baseline
- ✓The pre-ship checklist for core quality, code/scripts, and testing
Highlights
- •Dozens of good/bad SKILL.md examples
- •The 'Claude A / Claude B' iterative authoring method
- •Concrete anti-patterns to avoid (magic constants, deep nesting, too many options)
Who It’s For
Best For
- ✓Skill authors moving from prototype to production
- ✓Teams standardizing internal skill libraries
Prerequisites
- •Read the Agent Skills overview first
- •Basic Python/bash for the code-bundling sections
FAQ
What is Skill authoring best practices — Claude Docs?
Anthropic's official best-practices guide for authoring Skills: writing discoverable descriptions, setting the right degree of freedom, progressive-disclosure patterns, and evaluation-driven iteration. Best for anyone shipping a real Skill.
Is Skill authoring best practices — Claude Docs free?
Skill authoring best practices — Claude Docs is free to access.
What level is Skill authoring best practices — Claude Docs for?
Skill authoring best practices — Claude Docs is aimed at a intermediate audience. Recommended background: Read the Agent Skills overview first, Basic Python/bash for the code-bundling sections.
How long does Skill authoring best practices — Claude Docs take?
Expect roughly ~25 min read. Most learners work through it at their own pace.
What will I learn from Skill authoring best practices — Claude Docs?
You'll learn: How to write descriptions that make a Skill discoverable and correctly triggered; Matching a task's 'degree of freedom' to instructions vs. exact scripts; Progressive-disclosure structuring rules (500-line limit, one-level references, TOCs); Building evaluations first and iterating Skills against a baseline; The pre-ship checklist for core quality, code/scripts, and testing.