Skills

Agent Skills is an open format: a skill is a folder that must contain a SKILL.md, which starts with a name and a description followed by the instructions. It can also bundle scripts, references, and templates.

Why it works: loading on demand

1. Discovery. At startup the agent reads only each skill's name and description, which costs very little context.
2. Activation. When a task matches a skill's description, the full SKILL.md is read in.
3. Execution. The agent follows the instructions, running bundled scripts or reading reference files as needed.

So you can keep many skills on hand without crowding the context the way stuffing every procedure into AGENTS.md would.

Writing a good skill

• The description decides whether it gets used. Say when to use it, including how a user might phrase the request, e.g. "Use when the user asks to release a new version or write a changelog."
• Write steps as an executable checklist. For each step, say which command to run and what result to check.
• Turn deterministic parts into scripts. If a script can do it, do not make the model reason it out every time.
• Say what to do on failure. Which failures mean stop and ask a human.

Folder layout

release/
├── SKILL.md       # Required: name, description, instructions
├── scripts/       # Optional: executable scripts
├── references/    # Optional: reference docs
└── assets/        # Optional: templates and other resources

Where skills live depends on the tool (a skills folder in the project or your user directory), but the folder itself works across tools that support Agent Skills.

---
name: release
description: Use when releasing a new version to bump the version, write the changelog, and tag. Triggers on "release", "cut a version", or "write the changelog".
---

# Release a new version

## Preflight
1. Run `git status` and make sure the working tree is clean; if not, stop and ask me.
2. Run `pnpm check`; everything must pass.

## Steps
1. Read commits since the last tag: `git log $(git describe --tags --abbrev=0)..HEAD --oneline`.
2. Pick the version from Conventional Commits: `!` or `BREAKING CHANGE` bumps major, `feat` bumps minor, otherwise patch.
3. Add a section at the top of `CHANGELOG.md`, grouped into Features / Fixes / Other, one sentence per item.
4. Update `version` in `package.json`.
5. Show me the changes for confirmation, then commit and tag `v<version>`.

## Do not
- Do not push tags or publish to npm unless I ask.