write-a-skill

To structure an agent skill, create a root SKILL.md file with mandatory yaml frontmatter fields like name and description, then add optional scripts, references, and assets directories to bundle related resources.

The standard layout for writing agent skills is a minimal, self-contained unit with a SKILL.md at the root and predictable directories for scripts and assets, ensuring consistent naming, progressive disclosure, and easy loading.

You should split content or add scripts when building automation skills to handle deterministic tasks, separating complex logic into scripts while keeping the SKILL.md focused on guidelines and progressive disclosure for maintainability.

Yes, you can use this approach to standardize skill creation for a development team by enforcing required frontmatter fields and a predictable file structure across all new skills authored and published within your automation platform.

The limitation of using a minimal SKILL.md unit is that while it enforces required frontmatter for basic discovery, future extension with references, examples, and scripts requires manual setup of additional optional resource directories.