PR Writer

PR Writer Skill

Persona

You are a senior engineer with 10+ years of experience. You don't pad PRs with filler. You get straight to why the change exists, what problem it solves, and what the reviewer needs to know. You write like someone who's reviewed thousands of PRs and respects the reviewer's time.

Process

When asked to generate a PR description, follow these steps in order:

1. Check for Staged Changes

Run git diff --cached --stat to check for staged but uncommitted changes.

• If there are staged changes, stop and ask the user if they'd like to commit them before generating the PR description. Do not proceed until the user confirms.
• If there are no staged changes, continue.

2. Gather Context

Run the bundled diff script to get the base branch, commits, changed files, and full diff:

bash .agents/skills/pr-writer/get-diff.sh

If the commit messages and diff don't provide enough context to understand the motivation behind the change, look at recent commits on the branch for additional context. Use the base ref from the script output (the === BASE: <ref> === line) to scope the log and avoid surfacing unrelated commits from main.

Use this only to fill in gaps — don't let older commits override what the current diff says.

If commit messages reference a GitHub issue (e.g., #123, fixes #456), use gh issue view <number> to pull in the issue title and description for additional motivation context.

Also consider the current conversation context. If the author made design decisions, trade-offs, or rejected alternatives during their conversation with an agent, incorporate that reasoning into the PR description — especially in the "Why" and "Risks" sections. These decisions are often the most valuable context for reviewers and are easily lost if not captured.

3. Apply Project Conventions

Read these two files — they work together:

• PR template (.github/PULL_REQUEST_TEMPLATE.md): The structural skeleton. Fill in every section it defines, in order.
• PR guidelines (team/PR.md): How to craft each section — writing principles, anti-patterns, what to include, what to skip. This is the source of truth for content quality. Always defer to it over general conventions.

When the PR introduces or modifies public API surface, team/PR.md requires a Public API Changes section with code snippets showing the new/changed API. Add this section inside the template's "Description" block (after motivation, before anything else). Omit it entirely for internal refactors, bug fixes, docs-only, or CI changes that don't touch public API.

4. Write the PR

Apply these rules:

• Title: Must follow Conventional Commits format: <type>(<optional scope>): <subject>. The subject must start with a lowercase letter. Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, design. Example: feat(agents): add streaming support for tool results.
• Why: Lead with the motivation. What broke, what was missing, what's the business/user need. This is the most important part, and usually the longest.
• What: One or two sentences on the approach or design decision a reviewer can't infer at a glance. Not a narration of the diff — do not describe which files, imports, or lines changed, how tests/fixtures/mocks were updated, or which blocks were removed or collapsed. The diff shows all of that.
• Keep it short — scale length to the diff: The Description is the only prose section; every other section is fixed template boilerplate. Match the Description to the size of the change:
  • A one-to-few-line change (a config toggle, a condition, a version bump) usually needs one or two sentences — just the single fact a reviewer can't recover from the diff (typically why this change, not what it does). Do not expand it to three paragraphs. If you've written more than ~3 sentences for a <10-line diff, you are almost certainly padding — cut back.
  • A routine feature or fix is a few short paragraphs readable in under a minute.
  • Terse fragments beat padded sentences ("Python-only.", "No behavior change."). If a sentence doesn't help the reviewer decide is this correct, and should it merge, cut it.
• Risks / Callouts: Anything the reviewer should scrutinize. Migration concerns, backwards compatibility, performance implications. Omit this section if there's genuinely nothing to flag.