Specification

The complete format reference for SKILL.md files.

SKILL.md

Every skill is a directory containing a SKILL.md file. The file uses YAML frontmatter for metadata and Markdown for instructions.

SKILL.md

---
name: weather
description: Get current weather and forecasts (no API key required).
license: MIT
metadata:
  author: sundial
  version: "1.0"
allowed-tools: Bash Read
---

# Weather

Two free services, no API keys needed.

## wttr.in (primary)

Quick one-liner:

```bash
curl -s "wttr.in/London?format=3"
```

## Open-Meteo (fallback, JSON)

```bash
curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"
```

Frontmatter fields

Field	Required	Description
`name`	Yes	Unique identifier. Lowercase, dashes allowed (max 64 chars). Must match the parent directory name.
`description`	Yes	One-line summary (max 1024 chars). Agents use this to decide when to activate the skill.
`license`	No	SPDX license identifier (MIT, Apache-2.0, etc).
`metadata`	No	Freeform key-value mapping. Common keys: author, version, emoji, install steps.
`allowed-tools`	No	Space-delimited list of tool names the agent may use with this skill. (Experimental)
`compatibility`	No	Environment requirements note (e.g. "Requires git, docker, jq").

Only name and description are required. Everything else is optional and can be added as your skill grows.

Markdown body

The body after the frontmatter is freeform Markdown. There are no required headings or structure — write whatever instructions your agent needs. Common patterns include:

When to use — trigger conditions
Steps / workflow — numbered instructions
Examples — input/output pairs
Code blocks — commands the agent should run
Guardrails — things the agent must not do

Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files in references/.

Optional directories

Skills can include extra files alongside SKILL.md:

Directory	Purpose
`references/`	Documentation the agent reads on demand. Referenced in SKILL.md instructions.
`scripts/`	Executable helpers (shell, Python, etc). The agent runs these via tool calls.
`assets/`	Templates, config files, or other resources.

github/

├── SKILL.md
└── references/
    ├── get-started.md
    └── cli-examples.md

The SKILL.md body should tell the agent where these files are and when to read them, e.g. references/get-started.md.

Examples

Code review skill

code-review/SKILL.md

---
name: code-review
description: Perform structured code reviews following best practices.
license: MIT
metadata:
  author: sundial
  version: "1.0"
allowed-tools: Read Glob Grep
---

# Code Review

You are an expert code reviewer.

## Review Process

1. **Understand context**: What is the code trying to do?
2. **Check correctness**: Does it work as intended?
3. **Assess quality**: Is it maintainable and well-structured?
4. **Identify issues**: What problems exist?
5. **Suggest improvements**: How can it be better?

Skill directory layout

my-skill/

my-skill/
├── SKILL.md
├── references/
│   └── style-guide.md
└── scripts/
    └── helper.sh