creating-agent-skills

Structure Claude Code Skills using a SKILL.md file with required YAML frontmatter and a markdown body. Split content into workflows, references, templates, and scripts directories for modularity and progressive disclosure.

Progressive disclosure in agent skill development separates instructions into workflows, references, templates, and scripts. This modular structure ensures Claude Code loads only necessary context, improving efficiency and reducing token usage.

Write effective YAML frontmatter by following Anthropic's official specifications for skill structure. Include required metadata fields and clear descriptions to ensure your agent skills are properly parsed and discoverable.

Common anti-patterns in agent skill authoring include poor markdown body formatting, lack of progressive disclosure, and vague description writing. Following best practices for structure and naming conventions prevents these discoverability issues.

Split Claude Code Skill content into separate reference files when supporting documentation grows large. Using references and workflows directories enables progressive disclosure, keeping the main SKILL.md concise while providing detailed context on demand.