authoring-skills

To create an agent skill, add a new SKILL.md file under the target skill directory and populate it with YAML frontmatter containing the required name and description fields, followed by a structured content body. Follow the specified naming conventions to maintain consistency.

AGENTS.md is always loaded to provide global context, whereas individual SKILL.md files are loaded on demand to manage complexity. Separating content between AGENTS.md and per-skill SKILL.md ensures clarity by keeping globally relevant instructions distinct from specific skill workflows.

When authoring skills, the YAML frontmatter in a root SKILL.md requires two mandatory fields: name and description. You must also include a content body detailing the skill's functionality, and can optionally use directories like scripts/, references/, and assets/ as needed.

For complex agent skills, use hub-and-detail patterns by separating content into optional files like workflow.md and examples.md. This structure allows you to manage complexity by breaking down intricate workflows and examples into distinct, maintainable sections within the skill directory.

Yes, you can use optional directories such as scripts/, references/, and assets/ within your skill folder. These directories are documented to be used as needed, allowing you to organize supporting code, reference materials, and media files alongside your SKILL.md.