Ten agent skills worth writing first, with the template for each

The skills worth writing are not the clever ones. They are the procedures a team does every week, that three people do three ways, and that a new hire gets wrong for a month. Each of the ten below is a task somebody asks for by name, with steps that can be written down and a part a script does better than a person. Write them in this order, roughly by how often they fire.

The template they all share

1 · Commit messages

• Trigger: "Writes a commit message for the staged changes in the team’s convention. Use when asked to commit, or for a commit message. Not for PR descriptions."
• Steps: read git diff --staged; one subject line under 72 characters in the imperative; a body that says why, not what; reference the issue if the branch name carries one.
• Script: none needed — the diff is the input. A check that the subject has no trailing period is a one-liner worth having.
• Stop: nothing is staged; the diff mixes two unrelated changes.

2 · Pull request descriptions

• Trigger: "Writes a PR description from the branch’s commits and diff. Use when opening a PR or asked for a PR description."
• Steps: list commits since the base; summarise the change in two sentences a reviewer can act on; a testing section that says what was run; a risk line; screenshots where the diff touches UI.
• Script: scripts/pr-context.sh printing base branch, commits and changed files, so the model reads one page rather than the whole diff.
• Stop: the branch has no base it can find; the diff is over a size you name.

3 · Reviewing a PR against the checklist

The most valuable of the ten, because a checklist review is exactly the thing people skip when tired and models do not.

• Trigger: "Reviews a pull request against the team checklist and reports findings with file and line. Use when asked to review a PR or a diff. Does not approve or merge."
• Steps: the checklist itself, one item per line — error handling, input validation at the boundary, tests for the changed behaviour, a migration for every schema change, no secrets, no new dependency without a reason; report each finding as file, line, what and why; say what was checked and found fine.
• Script: a linter or type-check run whose output the review quotes rather than reproduces.
• Stop: the diff touches auth, billing or migrations — flag for a human rather than pass.

4 · Writing a database migration

• Trigger: "Writes a schema migration in the project’s format with a matching down. Use when asked to add, change or drop a table or column."
• Steps: the expand-and-contract rule (add, backfill, switch, drop — never rename in place); a down that restores exactly; an index for every new foreign key; the filename convention.
• Script: scripts/new-migration.sh <name> that creates the timestamped pair, so the model never invents a timestamp.
• Stop: the change would lock a large table; the column is referenced by code the diff does not touch.

5 · Release notes

• Trigger: "Writes release notes from merged PRs since the last tag. Use when asked for release notes, a changelog entry, or what shipped."
• Steps: run the script; group Added, Changed, Fixed, Security; one user-facing line per PR; the version comes from the tag, never invented.
• Script: scripts/changelog-since.sh <tag> listing merged PRs with labels.
• Stop: no tag; a dirty tree; more PRs than fit a release.

6 · Upgrading a dependency

• Trigger: "Upgrades one dependency and reports what changed. Use when asked to bump, upgrade or update a package."
• Steps: read the changelog between the versions; upgrade one package at a time; run the tests; list every breaking change with the file it touches; never upgrade a major version silently.
• Script: one that prints the changelog or release notes between two versions from the registry, so the model reads it rather than remembers it.
• Stop: a major version; a failing test the upgrade introduced; a transitive change that touches the lockfile in more than the one package.

7 · Incident write-ups

• Trigger: "Drafts a blameless incident write-up from a timeline. Use when asked for a post-mortem, an incident report or an RCA."
• Steps: the template’s sections in order — impact, timeline in UTC, contributing causes, what worked, actions with an owner; no names in the causes; every action a verb with a due date.
• Script: a timeline extractor that reads the incident channel export or the alert log and prints timestamps, so the timeline is data.
• Stop: the timeline has gaps longer than an hour; the cause is not yet known — say so rather than fill it.

8 · Writing tests for a change

• Trigger: "Writes tests for the behaviour a diff changes, in the project’s test framework. Use when asked to add tests or test coverage. Not for fixing failing tests."
• Steps: read the diff, list the behaviours it adds or changes, one test per behaviour, the failure case first, names that say the behaviour; run them; report what is still uncovered.
• Script: the test runner in single-file mode, so the loop is seconds.
• Stop: the behaviour needs a fixture that does not exist; the change is untestable without a refactor — say which.

9 · Reviewing an API design

• Trigger: "Reviews a proposed HTTP or library API against the team’s design rules. Use when asked to review an endpoint, a schema, or an interface before it is built."
• Steps: the rules — nouns for resources, no verbs in paths, errors typed and documented, pagination on every list, idempotency on every write, versioning stated; report each violation with the rule it breaks.
• Script: a schema validator for the format the team uses, whose output the review quotes.
• Stop: the design changes a public contract — flag it rather than approve it.

10 · Documentation in the house style

• Trigger: "Writes or edits documentation in the house style. Use when asked to document a feature, write a guide, or fix docs. Not for code comments."
• Steps: the style rules — second person, present tense, one idea per sentence, a working example before any prose about it, no "simply"; the page template; where the page goes in the tree.
• Script: a prose linter with the team’s word list, run before the draft is returned.
• Stop: the feature’s behaviour is not clear from the code — ask rather than describe what it probably does.

What the ten have in common

Each names an ask a person actually makes. Each has steps that fit on a screen. Each pushes the deterministic part into a script, so the model spends its judgement on wording and edge cases rather than on listing files. And each says when to stop — which is the line that separates a skill a team trusts from one that produces confident, slightly wrong output on the day it matters.

Write the first three this week and watch the transcripts. The description that does not fire, the step that gets skipped and the stop condition that was missing are all visible in the first ten sessions, and fixing them is a sentence each. The eleventh skill is whichever task your team asked for by name next.