creating-agent-skills

Structure a SKILL.md file by combining YAML frontmatter for metadata, a pure XML body for content, and progressive disclosure to link external references, keeping the main file concise and manageable.

Progressive disclosure in skill authoring is a design pattern that keeps the main SKILL.md minimal by linking to separate reference files and workflows, preventing context overload and maintaining Claude Code processing efficiency.

Validate and test Claude Code skills by applying XML structure rules, checking YAML frontmatter consistency, and running the skill against provided build, debug, validate, and ship workflow templates to catch anti-patterns.

Use a router pattern in skill design when your SKILL.md needs to direct Claude Code to multiple distinct workflows or references, ensuring the agent loads only the necessary context for a specific task.

Common anti-patterns include overloading the main SKILL.md with excessive content instead of using progressive disclosure, writing invalid XML structures, and failing to properly define YAML frontmatter metadata for Claude Code routing.

Creating a maintainable Claude Code skill without external references is possible but discouraged. The standard approach uses progressive disclosure and linked reference files to keep the core SKILL.md manageable as complexity grows.