skill-development

To structure a Claude Code plugin skill, create a directory with a SKILL.md file containing required YAML frontmatter (name and description) and a lean Markdown body. Move detailed operational guidance into separate referenced files to enforce progressive disclosure.

Progressive disclosure in skill development is the practice of keeping the main SKILL.md file lean by moving detailed content into a references directory. You should use references when your skill requires extensive operational guidance, ensuring the core file remains readable.

The best way to organize reusable resources is to group them into dedicated directories such as scripts/, references/, and assets/. This layout standardizes skill creation, ensures clear guidance, and simplifies maintenance for plugin developers.

Yes, a Claude Code plugin skill requires specific frontmatter fields to function. The SKILL.md file must include valid YAML frontmatter with at least the name and description fields defined to pass content quality validation.

Skill validation fails when the SKILL.md lacks required frontmatter, the body contains too much detailed content instead of using references, or expected resource files in the references or assets directories are missing.

Yes, you can use existing plugin-dev examples as templates for building new Claude Code skills. They illustrate best practices for standardizing the skeleton, frontmatter, and resource layout while providing a repeatable framework for teams.