Creating high-quality agent skills following Claude's official best practices. Use when designing, implementing, or improving agent skills, including naming conventions, progressive disclosure patterns, description writing, and appropriate freedom levels. Helps ensure skills are concise, well-structured, and optimized for context efficiency.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
README.mdreferences/degrees-of-freedom.mdreferences/progressive-disclosure.mdreferences/workflows-and-validation.mdGuide for creating agent skills that follow Claude's official best practices.
Concise is Key: The context window is shared. Only add what Claude doesn't already know. Default assumption: Claude is already very smart.
Progressive Disclosure: Skills load in three levels:
Keep SKILL.md small: Target ~200 lines, maximum 500 lines. Move detailed content to reference files aggressively.
Single Responsibility: Each skill does one thing well.
Ask the user:
Get clear sense of: purpose, usage examples, triggers.
Based on the skill's nature, determine appropriate degree of freedom:
High freedom (text instructions): Multiple approaches valid, context-dependent decisions Medium freedom (templates + parameters): Preferred pattern exists, some variation acceptable Low freedom (exact scripts): Fragile operations, consistency critical
If uncertain, ask the user. See references/degrees-of-freedom.md for guidance.
Identify what to include:
Scripts (scripts/): Executable code for deterministic operations
References (references/): Documentation loaded as needed
Assets (assets/): Files used in output (templates, images, fonts)
skill-name/
├── SKILL.md (required - AI agent instructions)
├── README.md (optional - human-facing installation and usage guide)
├── references/ (optional)
├── scripts/ (optional)
└── assets/ (optional)
README.md vs SKILL.md:
Avoid creating: INSTALLATION_GUIDE.md, CHANGELOG.md, or other redundant docs. Use README.md for human-facing documentation.
---
name: skill-name
description: What the skill does and when to use it
---
Naming (use gerund form):
processing-pdfs, analyzing-spreadsheets, managing-databaseshelper, utils, tools, anthropic-*, claude-*Description (third person, include WHAT and WHEN):
Be specific and include key terms. Description is the primary triggering mechanism.
Use imperative form. Keep small (target ~200 lines, max 500). Include only:
For complex multi-step processes, see references/workflows-and-validation.md.
Example pattern:
## Quick start
[Basic usage]
## Advanced features
**Feature A**: See [references/feature-a.md](references/feature-a.md)
**Feature B**: See [references/feature-b.md](references/feature-b.md)
Keep references one level deep. See references/progressive-disclosure.md for patterns.
For files >100 lines, include table of contents at top.
Organize by domain when appropriate:
skill/
├── SKILL.md
└── references/
├── domain_a.md
├── domain_b.md
└── domain_c.md
Avoid: deeply nested references, duplicate information, generic file names.
❌ Windows-style paths (scripts\file.py)
❌ Too many options without a default
❌ Time-sensitive information
❌ Inconsistent terminology
❌ Deeply nested references
❌ Vague instructions
Progressive Disclosure: references/progressive-disclosure.md - Detailed patterns and examples
Degrees of Freedom: references/degrees-of-freedom.md - Guidance on appropriate freedom levels
Workflows and Validation: references/workflows-and-validation.md - Creating workflows with validation and feedback loops