write-pr-desc

Generate a GitHub Pull Request description. Creates structured, reviewer-centric PR descriptions with title, summary, why (before/after), implementation details, and impact. Use when user says "write PR description", "PR desc", "describe this PR", or "generate PR description".

⭐61stars🔀5forks📁View on GitHub🕐Updated Jan 8, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the creation of professional, reviewer-centric GitHub Pull Request descriptions. By analyzing git diffs and technical context, it generates structured documentation that emphasizes the 'why' behind changes, provides clear implementation details, and assesses potential risks, significantly accelerating the code review process and improving team collaboration.

Use Cases

  • Feature Launch Documentation: Automatically generate comprehensive PR descriptions for new features, outlining the primary changes, affected modules, and architectural trade-offs to give reviewers immediate context.
  • Bug Fix Clarification: Clearly communicate the root cause of technical issues by generating 'Before vs. After' scenarios that demonstrate the fix and its impact on system behavior.
  • Standardizing Team Workflows: Ensure consistent documentation quality across engineering teams by enforcing a standardized template that includes mandatory sections for testing coverage, risk assessment, and rollout plans.
  • Technical Debt & Refactoring: Summarize complex refactoring efforts by highlighting the motivation for change and providing ASCII diagrams to clarify updated system architecture or data flows.
namewrite-pr-desc
descriptionGenerate a GitHub Pull Request description. Creates structured, reviewer-centric PR descriptions with title, summary, why (before/after), implementation details, and impact. Use when user says "write PR description", "PR desc", "describe this PR", or "generate PR description".
compatibilityRequires git for diff context, optionally gh CLI for PR metadata.

Write PR Description

Generate a concise, factual, reviewer-centric Pull Request description.

Core Principles

  • Be concise, factual, and reviewer-centric
  • Use short sentences, bullet points, and specific nouns
  • Present tense, active voice
  • Never make up information — only use what's in the code
  • Focus on "why" over "what" — the diff shows what changed

Process

  1. Get the diff context (staged changes, branch diff, or PR diff)
  2. Understand what changed and why
  3. Generate description following the template below

Required Sections

Title (50 chars max)

Use imperative mood that completes: "If applied, this PR will..."

  • Start with action verb: Add/Fix/Update/Remove/Refactor
  • Capitalize first word, no period

Summary

Brief overview explaining what this PR accomplishes:

  • Primary change using imperative mood
  • Scope: packages/modules affected
  • Root cause (for bugs) or motivation (for features)
  • Feature flags or configuration changes

Why

Show the problem and solution through scenarios.

### [Component/Feature Name]
[One-line problem statement]

**Before:**
- Scenario: [specific situation] → [problem/outcome]
- Impact: [user/system effect]

[ASCII diagram if it clarifies flow - 5-10 lines]

**After:**
- Scenario: [same situation] → [fixed outcome]
- Impact: [improvement achieved]

[ASCII diagram of new flow if needed]

Implementation

3-5 bullets covering technical approach:

  • Key design decisions and trade-offs
  • New interfaces or patterns introduced
  • Breaking changes or migrations
  • Why this approach over alternatives
  • Reference related commits if multiple logical changes

Impact & Testing

**Risk:** [One line - what could break]

**Changes:**
- Performance: [complexity/latency if significant]
- Behavior: [user-facing/API changes]
- Security: [auth/data access if relevant]

**Testing:**
- Coverage: [what's tested]
- Manual validation: [if needed]

**Rollout:**
- [Feature flags, compatibility notes]
  • Links: [issues, RFCs]
  • Follow-ups: [TODOs with owners]

Constraints

  • Max ~200 lines total
  • Every section must add unique value
  • Concrete examples > abstract descriptions
  • Scenario-driven explanations
  • Include ASCII diagrams only when they clarify architecture

Examples

See EXAMPLES.md for bug fix and feature PR examples.