Create effective Agent Skills using progressive disclosure. For choosing validation and distribution tooling around skills, use ecosystem-guide.
When to Create a Skill
Create a skill when you notice:
- Repeating context across conversations
- Domain expertise needed repeatedly
- Project-specific knowledge the agent should know automatically
Progressive Disclosure
Skills load in 3 levels:
- Metadata (~27 tokens optimal, ~100 max) - YAML frontmatter for triggering
- Instructions (<50 lines recommended, 500 max) - SKILL.md body with core patterns
- Resources (unlimited) - references/ scripts/ assets/ loaded on demand
Key: Keep Levels 1 & 2 lean. Move details to Level 3. Use npx claude-skills-cli validate to check budgets.
Structure
my-skill/
├── SKILL.md # Core instructions + metadata
├── references/ # Detailed docs (loaded as needed)
├── scripts/ # Executable operations
└── assets/ # Templates, images, files
References
- quick-start.md - Creating your first skill
- writing-guide.md - Writing effective skills
- development-process.md - Step-by-step workflow
- skill-examples.md - Patterns and examples
- cli-reference.md - CLI tool usage
- anthropic-resources.md - Official best practices
- mcp-integration.md - MCP server integration patterns
- testing-guide.md - Testing methodology and checklists
- distribution.md - Sharing and distributing skills
- troubleshooting.md - Common issues and fixes