Structuring the Body: Steps, Examples, Gotchas

Say what to do, in order, with checks

The body is read after the skill triggers, so it should be a clear procedure. A useful structure: a one-paragraph purpose; when to use / not to use; numbered steps with exact commands or file paths; the expected output format (a template or example); verification (how to check the result is right); and gotchas (the mistakes you have actually seen). Be concrete ("run git describe --tags --abbrev=0") rather than abstract ("find the last tag appropriately"), give examples of good output, state what not to do, and prefer deterministic scripts for fragile steps (parsing, calculations, API calls) so the model orchestrates rather than improvises. Explain the why behind important rules; Claude follows rules better when it understands their purpose. Keep it focused and short; move details into referenced files.

A well-structured body (illustrative)

The headings are a pattern, not a requirement. Not run here.

# pr-review

Review a pull request against the team checklist and report findings. Read-only: never edits files.

## When to use
A PR number or branch is given and a review is requested. Do NOT use for writing new code.

## Steps
1. `gh pr diff <n>` to read the diff (stop and ask if it is over 800 lines).
2. Walk `references/checklist.md` item by item.
3. Run `python scripts/lint_diff.py <n>` and include its JSON output.
4. Report using the template in `templates/review.md`.

## Verify
Every finding cites a file and line from the diff. If a claim has no line, delete it.

## Gotchas
- Generated files under `gen/` are never reviewed.
- A failing check on `main` is not caused by this PR; say so, do not blame the diff.

Quick check: Why prefer a deterministic script for a fragile step?

• It gives repeatable results, so the model orchestrates instead of improvising
• Scripts are required by the file format
• Models cannot read text
• Scripts remove the need for descriptions