create-skill

Progressive disclosure in skill creation keeps the main SKILL.md file concise under 200 lines by offloading detailed instructions into optional resource directories like references and scripts for maintainability.

Structure a new agent skill by defining a mandatory SKILL.md file with YAML frontmatter, then organize supporting content into optional scripts, references, and assets directories for clear separation.

Best practices for agent skill documentation include keeping instructions concise, setting appropriate degrees of freedom for the agent, and thoroughly testing the skill across all available models.

Yes, YAML frontmatter is required in the SKILL.md file to define the skill's metadata, ensuring it is discoverable and properly structured for the agent to parse.

Agent skills often fail to trigger when the SKILL.md file exceeds the 200 line conciseness limit or lacks clear instructions, preventing the model from understanding the intended degrees of freedom.

Yes, you can use a references directory to organize agent skill resources, allowing you to offload detailed documentation from the main SKILL.md file and maintain a concise entry point.