YAML front matter
Use fields like name and description to declare identity and a one-line trigger case for retrieval.
Skill authoring guide
Structure your SKILL.md so agents trigger reliably, compose cleanly, and stay maintainable.
A solid skill answers “what and when” up front and “how and done” in the body. Names and descriptions should match real repo folders, CI job names, and automation hooks to reduce ambiguity for both humans and retrieval.
Steps & acceptance
List ordered steps in the body and state done criteria to reduce ambiguous model output.
Boundaries & anti-patterns
Spell out when not to use the skill, common pitfalls, or forbidden actions for safer refusals.
Tools & environment
Optionally note Cursor, Codex, MCP, or model preferences so teams know if it fits their stack.
Variables & placeholders
Use consistent placeholders (e.g. <REPO_ROOT>) and list how to fill them at the end. Avoid vague “use your
judgment” steps.
Versioning & migrations
Document breaking changes at the top; if you rely on external APIs, note minimum versions or sunset dates.