Skill authoring best practices — Claude Docs
by Anthropic
The only official source for the hard limits and the evaluation-first process behind good Skills.
Overview
Anthropic's authoring guide for Agent Skills, and the only official document that states the numeric constraints. Its core-principles section argues the context window is a public good and that only a Skill's name and description are pre-loaded at startup, so SKILL.md itself should assume Claude is already smart and add nothing it already knows — illustrated with a roughly 50-token good example against a 150-token verbose one. It then introduces degrees of freedom: high freedom (prose instructions) where several approaches are valid, medium freedom (parameterised pseudocode) where a preferred pattern exists, and low freedom (an exact script run verbatim) for fragile operations such as database migrations. Hard limits are spelled out: name is capped at 64 characters, lowercase letters, numbers and hyphens only, with anthropic and claude reserved; description is capped at 1,024 characters and must be written in third person; the SKILL.md body should stay under 500 lines; reference files must sit one level deep from SKILL.md; and files longer than 100 lines need a table of contents. Later sections cover progressive-disclosure layouts, checklist-style workflows, validator feedback loops, avoiding time-sensitive text, and an evaluation-driven process in which you build three evaluations before writing documentation and iterate with one Claude instance authoring while another is tested with it. Advanced sections address utility scripts, package availability differences between claude.ai and the API, fully qualified MCP tool names, and a final pre-publication checklist.
At a Glance
- Topic
- Skills
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~35 min read, plus time to write and test a Skill
- Provider
- Anthropic
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Write a description field that makes Claude reliably discover the right Skill
- ✓Apply the three degrees of freedom to match instruction specificity to task fragility
- ✓Structure SKILL.md for progressive disclosure with one-level-deep reference files
- ✓Stay inside the hard limits: 64-character name, 1,024-character description, 500-line body
- ✓Build three evaluations before writing documentation, then measure against a no-Skill baseline
- ✓Design validator feedback loops so Claude catches its own errors before finishing
- ✓Avoid the documented anti-patterns: Windows paths, magic constants and offering too many options
Highlights
- •The only source for the exact frontmatter limits — 64 characters, 1,024 characters, 500 lines
- •Codifies the Claude A / Claude B loop: one instance authors the Skill, a fresh one is tested with it
- •Every rule arrives with a paired good and bad example rather than prose alone
- •Closes with a runnable pre-publication checklist covering core quality, scripts and testing
- •Anthropic's companion anthropics/skills repository ships a template, a spec directory and production reference skills
Who It’s For
Best For
- ✓Developers packaging repeated procedures into reusable Claude Skills
- ✓Platform teams maintaining a shared internal skill library across an organisation
- ✓Anyone whose CLAUDE.md has grown into a procedure rather than a set of facts
Prerequisites
- •Comfortable writing Markdown and YAML frontmatter
- •Basic understanding of how an agent loads context at runtime
- •Some Python or Bash if you intend to bundle utility scripts
FAQ
What is Skill authoring best practices — Claude Docs?
Anthropic's authoring guide for Agent Skills: the exact frontmatter limits, the progressive-disclosure file layout, the three degrees of freedom for matching instruction specificity to task fragility, and an evaluation-driven workflow where you build tests before writing documentation. It ends with a pre-publication checklist you can run against any 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: Comfortable writing Markdown and YAML frontmatter, Basic understanding of how an agent loads context at runtime, Some Python or Bash if you intend to bundle utility scripts.
How long does Skill authoring best practices — Claude Docs take?
Expect roughly ~35 min read, plus time to write and test a Skill. Most learners work through it at their own pace.
What will I learn from Skill authoring best practices — Claude Docs?
You'll learn: Write a description field that makes Claude reliably discover the right Skill; Apply the three degrees of freedom to match instruction specificity to task fragility; Structure SKILL.md for progressive disclosure with one-level-deep reference files; Stay inside the hard limits: 64-character name, 1,024-character description, 500-line body; Build three evaluations before writing documentation, then measure against a no-Skill baseline; Design validator feedback loops so Claude catches its own errors before finishing; Avoid the documented anti-patterns: Windows paths, magic constants and offering too many options.
Topics
Sources
This page was written from 2 sources, 1 on domains other than platform.claude.com.