pr-creator

pr-creator

Write PR descriptions like a developer posting in Slack, not an AI summarizing a diff. The reviewer has none of your context, so the body answers what the diff cannot: why, what it costs if wrong, and where you want their view. The diff answers what changed.

• IS: creating or updating a GitHub PR's title, body, draft state, and reviewers, attaching visuals for a UI change, plus the commit restructuring and review path that make a large diff readable.
• IS NOT: changing the code in the diff or reviewing it for bugs (use tidy), watching CI and review comments after the PR exists (use pr-babysitter), or cutting npm releases (use autoship).

Reference Files

Workflow

Copy this checklist to track progress:

PR creation progress:
- [ ] Inspect the current branch and diff against the existing PR base, or the discovered default branch merge-base
- [ ] Existing PR? gh pr view --json url,state,isDraft (state OPEN means edit, not create)
- [ ] Linear ID from branch, commits, prompt, or issue link; no ID means no prefix
- [ ] Noisy commits or a >500-line diff? references/pr-polish.md, before pushing
- [ ] PR template present? Read it (paths under Templates)
- [ ] Draft title and body against Rules and Anti-patterns
- [ ] git push -u origin HEAD
- [ ] gh pr create (or gh pr edit); then gh pr view --json url,title and return the URL
- [ ] UI change with a video or screenshots? gh pr edit <n> --attach <file> after the final body, then gh pr view <n> --json body

Do not ask the user to approve the description first; the point is speed. They can ask for a rewrite and you run gh pr edit.

Rules

1. Title. With a Linear ID: ABC-123: Add auth flow. Without one: Add auth flow. Under 60 characters, no trailing period. If the repo lints PR titles (a semantic-pull-request or commitlint workflow under .github/workflows/), use its shape and put the ID at the end: feat: add auth flow (ABC-123). Linear links on the ID wherever it sits in the title.
2. Body. One short paragraph: what changed and why it matters. Length follows the change; a one-line body is fine for a one-line fix.
3. No fake why. If the reason is not in the prompt, the Linear issue, the branch, the commits, or the diff, leave it out rather than inventing one.
4. Risk and input only when real. One Risk: line for migrations, billing, auth, permissions, irreversible writes, wide blast radius, or a subtle behavior change. One Input wanted: line when a decision in the diff is still open and the reviewer's view would change it; name the decision, never "thoughts welcome". Otherwise nothing.
5. Testing only if real. Say what you ran only if you ran it. Never a Test plan section, never checkboxes.
6. Partial work. If this PR does not finish the Linear issue, keep the ID out of the title and write Part of ABC-123 in the body. Linear's default automation moves a linked issue to Done when the PR merges; the non-closing magic word links without closing.
7. Draft and reviewers only when asked. --draft for "draft" or "WIP"; gh pr ready promotes it later, gh pr ready --undo demotes. --reviewer alice,org/team only for people the user named; CODEOWNERS already requests owners.
8. Stop after the useful content. The harness's attribution setting owns the PR footer (Generated with Claude Code, session link). Never hand-write one, and never strip one the harness or a repo policy appends. Everything above the footer is this skill's; its one-paragraph body replaces the harness's default Summary and Test plan sections.