Skills

Create an agent skill

A skill is a folder with a SKILL.md: a name, a description that says when to use it, and the steps. Agents load it only when a task matches, so you can keep many.

Becomes the folder name and how people call it, e.g. /release-notes or $release-notes.

The agent decides whether to load the skill from this alone. Say what it does, then “Use when …”.

Steps
1.
2.
3.
4.

One per line. Hard limits the agent must follow.

Optional. One short example beats a paragraph of description.

Reference files

Spec checks

  • Passes: Name is lowercase-with-hyphens, 64 characters or fewer
  • Passes: Description is 1–1,024 characters (146)
  • Passes: Description says when to use it (“Use when …”)
  • Passes: At least two concrete steps

The skill. Agents read the name and description up front and load the rest only when the task matches.

release-notes/SKILL.md
---
name: release-notes
description: Write release notes from merged pull requests since the last tag. Use when asked for release notes, a changelog entry or a “what shipped” summary.
---

# Release Notes

## When to use

The user asks for release notes, a changelog or a summary of what shipped.

## Steps

1. Find the latest tag with `git describe --tags --abbrev=0`.
2. List merged PRs since that tag with `gh pr list --state merged --search "merged:>DATE"`.
3. Group them under Added, Changed, Fixed. Drop chores and dependency bumps.
4. Write one line per change in plain language, linking the PR.

## Rules

- Never invent a change that isn't in a PR.
- Keep each line under 20 words.
- If there are no merged PRs, say so instead of writing notes.

## Example output

```markdown
## 2.4.0

### Added
- Export prompts as SKILL.md (#212)

### Fixed
- Emoji in titles no longer breaks saving (#209)
```

## References

Read these only when you need them:

- [STYLE.md](references/STYLE.md)