skill-authoring

To validate Claude skill frontmatter, enforce required fields including name, description, and invocation within the SKILL.md file. This ensures reliable discovery and activation by maintaining a consistent Skill Unit structure under .claude/skills/.

Progressive disclosure for Claude skills is an on-demand loading mechanism supported by optional resources like references/ and gotchas.md. It is needed when you want to keep the main SKILL.md body concise while providing detailed subdocuments for safe execution when required.

Create a SKILL.md template by defining required frontmatter fields and a concise body. Standardize optional components like scripts/, references/, and assets/ to support progressive disclosure, enabling teams to onboard, audit, and maintain skills with consistent discoverability.

You do not need gotchas.md and references/ folders for every Claude skill, as they are optional components. However, the skill structure enforces requirements for these resources when supporting on-demand loading and safe execution of complex skills.

The best way to audit and maintain Claude skills is to enforce a consistent Skill Unit structure with validated frontmatter. Applying standardized templates and progressive disclosure guidelines allows teams to reliably discover, activate, and update skills across the repository.