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".
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.
| name | write-pr-desc |
|---|---|
| description | 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". |
| compatibility | Requires 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
- Get the diff context (staged changes, branch diff, or PR diff)
- Understand what changed and why
- 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]
Related
- 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.