SKILL.md specification

A SKILL.md file is YAML frontmatter followed by a Markdown body.

---
name: earnings-note
description: Turn an earnings call transcript into a structured investor note with key metrics, guidance changes and risks.
license: MIT
compatibility: claude, codex, cursor
allowed-tools: read, write
metadata:
  domain: finance
---

# Earnings note

## When to use
...

Required fields

name

• 1–64 characters
• lowercase letters a–z, digits 0–9 and hyphens only
• no leading or trailing hyphen
• no consecutive hyphens
• must match the folder name exactly

Valid: kyc-gap-finder · Invalid: KYC_Gap, -kyc, kyc--gap

description

• 1–1024 characters
• written so an agent can decide when to use the skill
• state the trigger and the output in one or two sentences

Optional fields

Field	Type	Notes
license	string	e.g. MIT, Apache-2.0, proprietary
compatibility	string	comma-separated agents the skill is tested against
allowed-tools	string	tools the skill is permitted to call
metadata	map	free-form string key/value pairs

Unknown keys are preserved but ignored by the runner.

The body

Everything after the closing --- is standard Markdown. Skillyard renders it as the skill instructions and passes it verbatim to the model at run time.

Validation on Skillyard

The builder blocks publishing until:

• name passes every rule above
• description is between 1 and 1024 characters
• the Markdown body is at least 200 characters
• one example input and one example output are provided

Drafts can be saved at any time; only publishing is gated.