Skip to main content

Skill specification

A skill must include SKILL.md. Add other files as the task requires.
my-skill/
├─ SKILL.md
├─ references/
│  └─ review-rules.md
├─ scripts/
│  └─ check_input.py
└─ assets/
   └─ report-template.md

SKILL.md

Use YAML frontmatter and a Markdown body. Metadata describes the name and purpose. The body explains inputs, steps, decisions, output, and error handling. Make the activation conditions clear.

references/

Store longer specifications, terminology, examples, and business rules. Explain when to read each resource instead of loading everything on every task.

scripts/

Store validation, conversion, or calculation code. Document the runtime, dependencies, input, output, and useful error messages. A method-only skill does not need scripts.

assets/

Store templates, images, and other resources used to produce deliverables. Include them in the package and keep relative paths accurate.

Instructions and compatibility

Use stable names and clear conditions. Do not instruct the Agent to skip authorization or treat external material as trusted instructions. Explain tool connections and permissions without packaging credentials. State supported clients and versions based on testing. Check activation, completion, resource loading, and verifiable results. Next: create a skill.