nebula: Skill for Claude Code

A PR description is read three times: by the reviewer deciding whether to open the diff, by the person six weeks later asking why the code looks like this, and by whoever searches the merged PRs for the why behind a change. Write for all three: high level first, a picture before a paragraph, the mechanism at the bottom where only the reviewer scrolls.

This skill produces the body. The title follows the commit-subject rule: what a user now gets, not what the diff did ("Workspaces as a top tab bar, and one nebula instance per checkout", never "feat(tui): add tabs").

What every PR body carries — no exceptions

1. A table of contents at the top, one link per ## section, so the reader clicks straight to the part they want. GitHub gives a PR body's headings no anchors of their own, so every linked heading ends with <a id="…"></a> and the link names that id with GitHub's prefix, #user-content-… — see GitHub anchors below; a dead TOC is worse than none.
2. Screenshots of the change. A TUI change without a picture is a claim. At least one PNG of the screen after the change; a before/after pair when the change replaces something. Captured with the SCREENSHOT HARNESS, hosted on the pr-assets branch (recipe below). A change with no screen (a daemon mechanism, a CLI flag) shows its terminal output in a fenced block and a diagram, and says why there is no screenshot.
3. A mermaid diagram of the change, in a ```mermaid fence — GitHub renders it inline. Draw the change, not the whole system: the new flow, the state that moved, the crates touched. flowchart, sequenceDiagram and stateDiagram-v2 cover nearly every PR here; the templates show which fits which shape.
4. Categories a reader can scan. Benefit groups (🚀 Launch faster, 🔔 Know when it's done) or change classes (✨ Feature · 🐛 Fix · 📝 Docs · 🧪 Tests · ♻️ Refactor) — one emoji per heading, never on the bullets. A fix files under the feature whose promise it keeps. Inside a section a bullet is a bold hook and a dash, then two to four indented sub-bullets of one fact each — the key or command in backticks, a setting in the Settings › Sessions › done_sound form, a behaviour — never a paragraph (2026-09-05: PR #30's first cut could not be glanced through). When the change touches something the user likes, one bullet says what stayed the same. Credit contributors inline: Thanks @handle (#NN). No file paths, symbols or line numbers above the technical overview.
5. A technical overview section, last before the notes, for the reviewer: the mechanism in a few sentences, the files that matter with a clause each, the rejected approach they would ask about, the gate ("make ci green: fmt, clippy, 687 tests"). Everything above it stays high level.
6. A risk section, directly above the technical overview: the author's own read of what merging could break, in the PR REVIEWER SKILL's order — 🔒 security and production-merge risk, ⚡ performance cost, 🧩 fit with the codebase's patterns — one table row each, rated Low / Medium / High with a one-clause why, a 🟢 / 🟡 / 🔴 verdict above the table, and a Rollback line saying what a git revert undoes and what it does not (a PROTOCOL VERSION bump, a migrated store, a pushed branch). "No risk" is never bare: a docs-only or prose-only PR says why nothing runs. The reviewer checks this read against the diff, so write it as the reviewer would, not as the seller. When the change adds a surface — the DAEMON execs a program, opens a socket, a route or a ClientRequest, reads a new config source, writes a file it did not before — the Risk section opens with an ### 🎯 Attack surface subsection above the verdict: one bullet per way in, saying who or what reaches it, what holds it, and what does not. The 🔒 row then rates the residue, not the whole list. One table cell is never enough for an exec surface (PR #42, 2026-09-09: the exec of a git-config path shipped as one cell, and the maintainer asked where the attack vectors were). The templates carry the block behind a guidance comment; a PR that adds no surface deletes it.
7. The footer. Every PR body ends with the line the harness gives you (currently 🤖 Generated with [Claude Code](https://claude.com/claude-code) plus the session link) — keep it verbatim, last, after a blank line.