creating-effective-skills

Claude skills should use gerund naming (verb+ing form), follow progressive disclosure patterns across metadata and references, and organize descriptions in third-person WHAT/WHEN format. This structure optimizes skill discoverability and context efficiency for Claude-powered agents.

Scaffold a new skill using the SKILL.md framework, which enforces frontmatter metadata, modular references, defined workflows, validation patterns, and tool-usage constraints. The framework guides naming conventions, description writing, progressive disclosure levels, and degrees of freedom for agent decision-making.

Progressive disclosure loads skill information across three levels: metadata for quick recognition, descriptions for context, and references for detailed implementation. This pattern reduces cognitive load and keeps prompt context efficient for Claude agents.

Group references into modular, focused sections that support the core task. Progressive disclosure ensures brief metadata and descriptions point to detailed references only when needed, maintaining compact SKILL.md bodies optimized for agent token usage.

Skills define explicit tool-usage constraints and workflow boundaries that balance agent autonomy with predictability. The framework guides appropriate freedom levels—from rigid templates to flexible workflows—based on the skill's task complexity and validation requirements.

Yes. The SKILL.md framework applies to designing, implementing, and refining agent skills across naming, descriptions, progressive disclosure, validation patterns, and workflow definition. It codifies best practices usable at any stage of skill development.