Skill Development

To structure a SKILL.md file for Claude Code plugins, you must understand the skill anatomy and apply progressive disclosure. This ensures your skill content is discoverable, efficient, and effective by organizing instructions clearly within the main file.

Progressive disclosure in Claude plugin development is a best practice for organizing skill content. It involves separating instructions in SKILL.md from detailed API docs in references/ and scripts/, ensuring Claude loads only what it needs to remain efficient.

The writing style for Claude skill documentation should use imperative and infinitive verbs with third-person descriptions. Following these best practices ensures your instructions are clear, actionable, and easily interpreted by Claude Code.

You should put plugin API documentation in the references folder when it contains detailed information that supports the core skill. Moving this content out of SKILL.md applies progressive disclosure, keeping the main instructions lightweight and efficient.

The best way to create scripts for a Claude Code skill is to organize executable code within a dedicated scripts/ directory. This separates logic from descriptive text in SKILL.md, ensuring your skill remains structured and effective.

Your Claude skill does not strictly need an assets folder to work effectively, but it is part of the standard skill anatomy. Use it to store supplementary files, ensuring your skill is fully structured and discoverable within the plugin.