creating-agent-skills

Designing Claude Code Skills with progressive disclosure involves keeping your SKILL.md concise while loading deeper knowledge through reference files and executable scripts only when needed. This pattern ensures robust, scalable skill architectures without overwhelming the context window.

Valid Claude Code Skills require specific frontmatter fields and structured XML tags to define workflows, references, and success criteria. Enforcing these structural requirements through validation hooks ensures the skill operates predictably within the Claude Code environment.

Auditing existing Claude Code Skills involves checking the SKILL.md structure against best-practice templates, verifying frontmatter requirements, and evaluating intake questions, routing logic, and verification patterns to identify areas for upgrading to router-based architectures.

Structuring reference files for Claude Code Skills requires separating deep knowledge into dedicated files loaded on demand. This approach keeps the main skill definition lightweight while providing executable scripts and detailed patterns when specific workflows are triggered.

Upgrading to a router-based architecture is necessary when a Claude Code Skill becomes too complex for a single file, requiring progressive disclosure to manage multiple workflows, conditional routing, and extensive reference patterns efficiently.

Templates can enforce validation hooks in Claude Code Skills by codifying frontmatter requirements, XML structure, and success criteria into reusable patterns. This ensures every new skill or audited skill adheres to consistent structural and operational standards.