create-agent-skills

Structure a SKILL.md file by defining metadata in YAML frontmatter and organizing content within an XML body, optionally adding references, scripts, or assets to support progressive disclosure and skill validation.

Progressive disclosure in skill design separates core instructions from detailed references, loading deeper context only when needed to keep the main SKILL.md concise and improve validation.

Best practices for skill metadata involve using consistent naming conventions, writing effective descriptions for discovery, and structuring YAML frontmatter accurately to ensure proper skill validation.

Validate Claude Code skills by checking YAML frontmatter structure, ensuring the XML body follows established skill design patterns, and verifying that optional references and scripts are correctly linked.

Yes, you can use external scripts and reference files when building skills to support progressive disclosure, allowing the main SKILL.md to remain focused while delegating detailed logic to auxiliary assets.

Skill structure validation and discovery often fail due to inconsistent naming conventions, poorly structured YAML metadata, or an overly complex XML body lacking progressive disclosure and clear descriptions.