write-a-skill

To create an agent skill package, draft a SKILL.md file with YAML frontmatter containing name and description fields, a trigger-based "Use when..." description, and a concise instruction template. This ensures proper structure and agent discoverability.

The best way to write YAML frontmatter for skill authoring is to include the name and description fields, optimizing the description using a strict "Use when..." format for trigger-based discovery. This ensures agents select the correct capability based on user intent.

Include deterministic scripts in your agent skill when operations require consistent, repeatable execution for workflow support. These scripts supplement the SKILL.md instructions and provide reliable utility for complex or automated tasks within the skill package.

Structure a SKILL.md file by keeping the instruction template concise while supporting progressive disclosure through references and examples. Place reference material and optional examples in designated locations to guide users through a step-by-step workflow.

Yes, your skill description must follow a strict "Use when..." format for trigger-based discovery. This format ensures the agent can accurately select the correct capability based on user intent and query context during skill matching.

When writing a new agent skill, keep the instruction template concise to stay within size guidelines and avoid overwhelming the agent. Limitations include ensuring descriptions include triggers and do not exceed the recommended structural scope for optimal performance.