write-a-skill

Structuring an agent skill requires a standard directory layout with a SKILL.md file, frontmatter, and optional folders for references and scripts to ensure consistent loading. The skill provides a repeatable skeleton for this exact purpose.

The recommended file layout for writing agent skills includes SKILL.md, REFERENCE.md, EXAMPLES.md, and optional directories like scripts/, references/, and assets/. This structure organizes content and reference materials for clear discovery metadata.

Writing SKILL.md frontmatter involves defining the skill name and a concise description at the top of the file. The skill provides templates and best practices to guide authors through creating this metadata.

Yes, you can include optional scripts and references when authoring agent skills by organizing them in dedicated directories. The skill framework supports adding these resources alongside the main SKILL.md file with minimal churn.

You should split content into separate reference files when the skill documentation becomes too dense for a single file. The skill provides best practices on when to divide content and how to organize reference materials effectively.

The best way to draft a domain-specific skill for a team is to start with a concise SKILL.md definition using provided templates. This approach allows the team to fold the new skill into the repository with clear discovery metadata.