Pr Writer

SentryOfficialPublished by Sentry

Skill
Content generator
Software development
Apache-2.0
No issues found

From the author

Create or refresh reviewer-facing PR titles and descriptions. Use when opening a PR, updating its title or body, or preparing branch changes for review.

— the description by Sentry

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

PR Writer helps developers create clear, concise, and effective pull request documentation. Instead of generating generic changelogs or repetitive templates, it focuses on explaining the 'what' and 'why' of a change to reduce the cognitive load on reviewers. It analyzes the current branch diff and repository context to produce structured titles and bodies that highlight concrete behavioral changes, impact, and necessary migration guidance.

What it does

Analyzes current branch diffs and repository context to draft PR content.
Enforces conventional commit-style titles for clarity and consistency.
Provides structured templates based on the complexity and type of change.
Guides the user to include only essential context like breaking changes or risk factors.
Supports updating existing PRs to reflect the current state of the code.
Prevents clutter by omitting redundant sections like test plans or file lists.

When to use it

When opening a new pull request and needing a professional description.
When a PR has evolved significantly and the original description is no longer accurate.
When preparing a complex change that requires clear communication of breaking impacts.
When you want to ensure your PR focuses on reviewer impact rather than implementation details.

Advantages

Reduces reviewer friction by focusing on behavioral impact.
Standardizes PR communication across a team or project.
Prevents the inclusion of unnecessary boilerplate or PII.
Ensures documentation stays synchronized with the actual code diff.

Usage examples

“Draft a PR description for my current feature branch that adds a new API endpoint.”: The agent inspects the diff and generates a concise PR body explaining the new endpoint's purpose, the affected API surface, and any necessary integration steps for consumers.
“Refresh the description for PR #123 to reflect the recent breaking change in the data schema.”: The agent analyzes the diff, identifies the breaking contract change, and updates the PR body with a clear before/after example and migration guidance.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/getsentry/pr-writer/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip pr-writer.zip -d .agents/skills
```

Documentation by Sentry

PR Writer

Write the PR body as a cover note for reviewers, not a changelog, template, validation log, or file-by-file summary.

Inspect the Change

Requires authenticated gh. Inspect the current branch, working tree, PR, base branch, commits, and full diff:

git branch --show-current
git status --porcelain
gh pr view --json number,title,body,url,baseRefName,headRefName
gh repo view --json defaultBranchRef

If gh pr view reports that no PR exists, continue with first-time PR creation. For an existing PR, use its baseRefName; otherwise use the repository default branch. Set BASE, then inspect:

git log "$BASE"..HEAD --oneline
git diff "$BASE"...HEAD

If on main or master, create a feature branch first. Ensure intended changes are committed and review the whole branch diff, not only the latest commit or existing PR text.

Core Rules

Describe concrete changed behavior, affected surfaces, and reviewer impact before implementation detail.
Explain motivation, risk, tradeoffs, migration, or review focus only when useful.
Use the smallest structure that makes the change easier to review.
Replace internal prompt or process terminology with specific behavior.
When refreshing a PR, rewrite around the current full diff without narrating review history.

Titles

Use <type>(<scope>): <subject> or <type>: <subject>.

Allowed types: feat, fix, ref, perf, docs, test, build, ci, chore, style, meta, license, and revert.

Describe the dominant full-branch change with the narrowest accurate type and scope.
Use ! only when the change breaks an external contract, and explain the affected surface in the body.
Avoid vague subjects such as update, cleanup, misc, fix stuff, or address feedback. Do not add a trailing period.
Keep an existing title only when it still describes the whole diff.

Body Shape

Choose the minimum useful shape:

Change	Include
Small or obvious	One concise paragraph without headings.
Feature, bug fix, or refactor	Changed behavior and effect; add root cause, unchanged behavior, or non-obvious approach when relevant.
Contract or breaking change	Affected API, schema, payload, config, permission, storage, or CLI surface; include compatibility and migration guidance.
Operational, visual, or workflow change	User/operator effect, measured impact, failure modes, or flow when useful.
Broad, generated, or cross-cutting change	Organizing principle, why the breadth is necessary, and where review should start.

Default:

<What changed and what effect it has.>

<Why the approach, risk, migration, or review focus matters, if not obvious.>

For review-feedback updates, describe the resulting PR as a whole rather than the sequence of revisions.

Reviewer Aids

Use an aid only when it reduces reviewer reconstruction work:

A compact before/after or interface example for changed contracts.
A small Mermaid diagram for async flows or state transitions.
A screenshot or recording note when visual evidence exists.
A rollout, compatibility, risk, or review-order note when reviewers or adopters need it.

Introduce an artifact with one sentence explaining what reviewers should notice. Omit it when prose is clearer.

Boundaries

Do not add default Summary, Changes, or Test Plan sections.
Omit routine validation unless it changes risk assessment or explains meaningful regression coverage. For docs, skills, copy, or config changes, omit it by default.
Do not paste commands, CI logs, validation dumps, commit logs, placeholders, or exhaustive file lists.
Never include customer or organization names, user emails, support ticket contents, secrets, or PII.
Use issue references only when verified from user input, branch names, commits, PR discussion, or tracker output. Fixes <issue> closes; Refs <issue> only links.

Create or Update

Create new PRs as drafts. Write the body to a temporary Markdown file, then run:

gh pr create --draft --title '<title>' --body-file /tmp/pr-body.md

Update existing PRs with gh api:

gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
  -f title='<title>' \
  -F body=@/tmp/pr-body.md

Refresh the title and body when follow-up commits materially change scope, approach, breaking behavior, risk, migration, or review expectations. Skip typo-only, formatting-only, and rename-only follow-ups.

Examples

Small change:

The AI Customizations section now starts collapsed so it does not consume
sidebar space before users need it. Expanding it preserves the existing saved
preference behavior.

Breaking contract:

Run logs now emit chunk-level records instead of one skill-level record.
Consumers that read top-level `findings` must iterate over
`chunk.findings` for each record.

Before:

```json
{"skill": "security-review", "findings": [...]}
```

After:

```json
{"schemaVersion": 1, "chunk": {"index": 1, "findings": [...]}}
```

Files

ATTRIBUTION.mdAdded by AutoGineer842 B
EVAL.md1.6 KiB
LICENSELicence file added by AutoGineer10.5 KiB
SKILL.md5.2 KiB
SPEC.md12.3 KiB
evals/axis.config.json318 B
evals/scenarios/concise-docs-pr.json1.7 KiB

SPEC.md

PR Writer Specification

Intent

The pr-writer skill creates and updates pull requests with concise, review-oriented titles and descriptions that match Sentry conventions.

Its main job is to turn branch changes into a reviewer-facing cover note that explains what changed, why it changed, and the few details reviewers need before reading the diff. The output should adapt to the size, risk, and shape of the change: simple PRs should stay terse, while broad, risky, breaking, API/schema, migration, generated, or workflow-heavy PRs should include only the extra structure that makes review easier.

The skill should offer the agent a small menu of optional reviewer aids, such as before/after examples, schemas, interfaces, Mermaid diagrams, screenshots, rollout notes, migration notes, review order, or risk callouts. These are decision tools, not required sections. The agent should choose them with simple heuristics and its own judgment, then omit anything that does not materially improve reviewer understanding.

Scope

In scope:

Creating draft pull requests from committed feature branches.
Updating existing PRs by re-evaluating both title and body against the full branch diff against the base branch.
Producing natural PR bodies that default to short paragraphs and use structure only when the change shape needs it.
Choosing optional reviewer aids based on the actual diff shape, including code snippets, payload examples, schemas/interfaces, diagrams, screenshots, review-order notes, rollout notes, migration notes, or risk/tradeoff callouts.
Producing titles that accurately describe the dominant change in the PR.
Including issue references, breaking-change context, and review focus when useful and supported by known evidence.

Out of scope:

Writing commits or deciding commit history policy.
Running full CI or iterating on failing checks.
Producing release notes, changelogs, or customer-facing announcements.
Including mechanical test-plan checklists in PR bodies.
Mirroring repository PR templates, including empty headings, placeholder checklists, rote "Summary / Test Plan" sections, or validation logs that do not help reviewers understand the change.
Creating decorative diagrams, exhaustive file-by-file walkthroughs, or copied diffs that make the body longer without reducing reviewer effort.

Users And Trigger Context

Primary users: engineers and coding agents preparing Sentry pull requests.
Common user requests: open a PR, update a PR, refresh a PR after scope changes, address review feedback after follow-up commits, prepare changes for review.
Should not trigger for: code review requests, commit-only requests, CI-fix loops, or generic documentation writing.

Runtime Contract

Required first actions: verify the current branch, committed state, base branch, and diff scope before writing or updating a PR; when updating, use the PR's baseRefName as the base branch and inspect the current PR title and body before deciding what to keep.
Required outputs: a conventional PR title and a concise, natural PR body suitable for gh pr create or GitHub API update commands; on updates, include an explicit keep-or-rewrite decision for the title.
Required body-shape decision: decide whether the change is small/obvious, bug fix, feature, refactor, API/schema/payload/config/CLI change, breaking change, migration, performance/reliability change, broad/generated/cross-cutting change, UI change, workflow/architecture change, or review-feedback update. Use the decision to select the minimum useful structure.
Required update behavior: if an open PR exists and follow-up commits materially change reviewer expectations, refresh the PR even when the user did not explicitly ask for a PR edit.
Optional reviewer aids: use before/after blocks for contract or behavior comparisons; schemas or interface snippets for API, payload, type, config, event, or storage changes; Mermaid sequence/flow/state diagrams for async flows, queues, state transitions, lifecycle changes, or multi-component interactions; screenshots or recordings for UI behavior; review-order notes for broad or generated PRs; rollout, migration, compatibility, feature-flag, or deprecation notes for changes that affect adopters or operations.
Hard negatives: do not add a Test Plan section by default, do not paste command transcripts, do not list routine validation as its own heading unless it changes risk assessment, do not add empty template headings, do not narrate every file, do not include Mermaid when prose is clearer, and do not include schemas or examples that merely duplicate obvious code.
Non-negotiable constraints: never include customer data or PII, never invent issue references, ignore repository PR templates, and prefer draft PRs for newly opened pull requests.
Expected bundled files loaded at runtime: only SKILL.md.

Source And Evidence Model

Authoritative sources:

Sentry engineering practices for code review.
Sentry commit message conventions.
Repository-level agent instructions.
Google Engineering Practices guidance for CL descriptions.
Git and Linux kernel patch submission guidance.
GitHub pull request reviewability guidance.
GitHub and GitLab Markdown support for Mermaid diagrams in PR/MR descriptions.
GitLab merge request template prior art for before/after visual comparisons and local validation only when useful.
Atlassian pull request guidance on using descriptions, reviewer navigation, and visuals to reduce reviewer reconstruction work.
Conventional Commits and changelog guidance for identifying and communicating breaking changes.
Observed user rejection of programmatic PR descriptions and preference for concise reviewer context.
getsentry/warden#265 as a formatting exemplar for before/after examples on schema and output-shape changes, only when direct comparison is warranted.

Useful improvement sources:

positive examples: PR descriptions that read like a human cover note and give reviewers the missing context.
positive examples: PR descriptions that use optional artifacts sparingly, such as a compact schema/interface, before/after payload, Mermaid flow, screenshot, rollout note, or review-order note when that artifact makes the diff easier to review.
positive examples: PR descriptions that use concrete behavior and reviewer impact instead of meta phrases like "decision model", "expanded contract", or "runtime guidance".
positive examples: PR titles that stay specific after follow-up commits.
negative examples: PR bodies that read like essays, repeat the diff, overuse headings, mirror a template, or leak internal agent process.
negative examples: PR bodies with rote Test Plan headings, pasted command output, generic validation details, decorative diagrams, oversized Mermaid blocks, unnecessary schemas, empty headings, or file-by-file narration.
negative examples: PR bodies that read like release notes for the prompt rather than a human cover note for the change.
negative examples: PR titles that are vague, process-oriented, or stale after scope changes.
negative examples: branches with material follow-up commits where the agent pushed changes but left the PR title/body stale.
commit logs/changelogs: only as source context, not as body text to paste.
issue or PR feedback: reviewer comments about missing context or excessive detail.
eval results: prompt-based checks for title accuracy, natural reviewer prose, justified structure, verified references, and privacy boundaries.

Data that must not be stored:

secrets
customer data
private customer, organization, or user identifiers
support ticket contents not needed for a public PR

Reference Architecture

SKILL.md contains runtime workflow, command patterns, conditional PR body guidance, examples, and safety constraints.
EVAL.md contains the maintainer playbook for evaluating pr-writer output quality.
evals/axis.config.json contains the AXIS configuration for running pr-writer evals with Codex.
evals/scenarios/ contains durable AXIS cases for PR title/body output regressions.
references/ contains no files currently; add focused style or evidence examples only if the runtime file becomes too long or repeated regressions show the examples need more room.
references/evidence/ contains no files currently; use it for durable positive and negative PR body examples if iteration data accumulates.
scripts/ contains no files currently.
assets/ contains no files currently.

Evaluation

Lightweight validation: run the AXIS command in EVAL.md for the current Codex-backed regression case, then compare generated titles and PR bodies against representative feature, bug-fix, schema-change, breaking-change, migration, UI, performance/reliability, broad-review, generated-change, workflow-diagram, and refactor prompts for brevity, clarity, justified structure, issue references, update-path title handling, and privacy handling.
Deeper evaluation: expand evals/scenarios/ with expected body shapes when regressions recur.
Holdout examples: include at least one simple PR that should be one paragraph, one bug fix that should explain root cause without file bullets, one PR with no known issue reference, and one API or input-format change that should use separate before/after fenced blocks.
Holdout examples: include at least one breaking contract change that should identify affected consumers and migration guidance, one workflow-heavy PR that should use a compact Mermaid diagram, one UI PR that should mention screenshots or visual evidence only if available, one broad generated PR that should explain generation/review order, and one small PR that must not grow a Test Plan or template headings.
Holdout examples: include at least one PR update where the old title no longer matches the whole PR diff and must be rewritten.
Holdout examples: include at least one review-feedback or follow-up-commit scenario where the skill should refresh an open PR without an explicit PR-update request.
Acceptance gates: output title uses an allowed Sentry conventional commit type, uses ! when the dominant change is breaking, matches the dominant change, update flows explicitly re-evaluate whether the existing title still fits, material follow-up commits to an open PR trigger a refresh even without an explicit PR-update request, output reads like natural reviewer-facing prose, default body uses paragraphs instead of generic headings, structure is present only when justified by the change shape, optional artifacts are used only when they reduce reviewer effort, body language describes concrete behavior and reviewer impact instead of internal process, breaking changes include affected surface and migration/compatibility context when known, before/after examples appear only when direct comparison is the clearest explanation, unknown issue references are omitted instead of invented, routine validation is omitted unless it changes reviewer risk assessment or explains coverage for changed behavior, and customer data is excluded.

Known Limitations

The skill cannot guarantee that issue references are correct unless the branch, commits, or user provide them. It must omit references rather than invent placeholders.
It relies on the agent's judgment to decide when a heading, bullet list, or before/after block helps reviewers more than plain paragraphs.
It relies on the agent's judgment to decide whether optional reviewer aids, such as schemas, diagrams, screenshots, migration notes, or review-order notes, reduce reviewer effort enough to justify their length.
Mermaid rendering support and syntax differ by platform/version, so diagrams must stay simple and should be omitted when uncertain or not essential.
It relies on the agent's judgment to decide when a title is still accurate enough to keep versus rewrite.
Very large PRs may still need more context than the default body shape encourages.

Maintenance Notes

Update SKILL.md when PR creation workflow, title rules, body template, examples, or safety constraints change.
Update SPEC.md when intent, scope, evaluation gates, or evidence policy changes.
Update EVAL.md and evals/ when the maintained regression cases, AXIS configuration, or evaluation gates change.
Add focused reference files only when examples or guidance would make SKILL.md noisy.
Keep public inventories pointed at the canonical skills/pr-writer skill, not mirrors.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs a command-line tool

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Sentry

Publisher

Sentry (Official)

Source

getsentry/skills · skills/pr-writer · commit e94f222

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Sentry or Sentry.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download pr-writer.zip