pr-description-writer

使用可视化图表、汇总表、可折叠部分和结构化测试计划生成全面、审阅者友好的 PR 描述。在不牺牲细节的情况下优化了可读性。

📖 中文导读:使用可视化图表、汇总表、可折叠部分和结构化测试计划生成全面、审阅者友好的 PR 描述。在不牺牲细节的情况下优化了可读性。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: pr-description-writer description: "Generate comprehensive, reviewer-friendly PR descriptions with diagrams, summary tables, collapsible sections, and structured test plans." allowed-tools: Bash Read Glob Grep

PR Description Writer Skill

When to Use This Skill

Use this Skill when:

  • Creating or updating a PR description for a feature branch.
  • The PR has multiple related changes that need clear organization.
  • You want a description that helps reviewers understand the "why" and "what" quickly while having access to detailed context.
  • You're preparing a PR for review and want it to be self-documenting.

This Skill is designed to work with any repository but is especially tuned for Django/Python backends, React frontends, and infrastructure changes.

Example Prompts

  • "Use pr-description-writer to create a PR description for my current branch."
  • "Generate a comprehensive PR description for PR #1234 using the pr-description-writer Skill."
  • "Update the PR description for my feature branch to match our standard format."

Workflow (High Level)

  1. Gather PR and branch context (see references/gh-cli.md for exact commands).
  2. Identify the base branch and enumerate all changes (committed + uncommitted).
  3. Write a layered, reviewer-centric PR description using the structure below.
  4. If the user wants, update/create the PR using gh (see references/gh-cli.md).

Core Principles

1. Scannable First, Detailed Second

Reviewers should understand the PR in 30 seconds from the summary, then dive deeper as needed. Structure content in layers:

  1. Summary table – Quick overview of key features (30 seconds)
  2. Visual diagrams – Understand flows without reading code (1-2 minutes)
  3. Detailed sections – Full context for each feature (as needed)
  4. Collapsible file lists – Reference without clutter

2. Visual Over Verbal

Use diagrams, tables, and structured formatting instead of prose where possible:

  • Decision trees for conditional logic
  • Flow diagrams for pipelines and processes
  • Tables for feature summaries and comparisons
  • Code blocks for commands and examples

3. Reviewer-Centric

Every section should answer a reviewer's question:

  • "What does this PR do?" → Summary
  • "Why was it done this way?" → Detailed sections with rationale
  • "What files should I focus on?" → Collapsible file lists
  • "How do I test this?" → Test commands + manual steps
  • "Are there breaking changes?" → Explicit callouts

4. Complete Picture

Never describe only the latest commit. The PR description must reflect:

  • All commits in the branch (from base to HEAD)
  • Any uncommitted changes the user plans to include
  • The cumulative effect of all changes together

PR Description Structure

Section 1: Summary

Start with a 1-2 sentence high-level summary, then provide a Key Features table if the PR has 3+ distinct features:

## Summary

This PR adds [brief description of the main change].

### Key Features

| Feature | Description |
|---------|-------------|
| **Feature A** | Short description of what it does |
| **Feature B** | Short description of what it does |
| **Feature C** | Short description of what it does |

For smaller PRs (1-2 features), a bullet list is acceptable.

Section 2: Visual Diagrams

For any non-trivial flow, include a visual diagram. Choose the appropriate format based on complexity:

ASCII Art (Simple Flows)

Use for decision trees and linear flows:

## Feature Flow

```
First condition?
     │
    YES ──► Has prior state? ──► YES: Action A
     │                       └──► NO:  Action B
     │
    NO ───► Action C
```

Mermaid (Complex Flows)

Use for multi-step pipelines, state machines, or architectures:

## Architecture

```mermaid
flowchart LR
    A[Step 1] --> B[Step 2]
    B --> C{Decision}
    C -->|Yes| D[Path A]
    C -->|No| E[Path B]
```

Box Diagrams (Pipelines)

Use for showing data flow or process stages:

## Data Pipeline

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Input Stage   │────►│  Process Stage  │────►│  Output Stage   │
│  (description)  │     │  (description)  │     │  (description)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

Section 3: Detailed Feature Sections

For each major feature, provide a dedicated section with:

  • What it does – Behavior description
  • Why this approach – Rationale for key decisions
  • Key implementation details – Important patterns or constraints

Use horizontal rules (---) to separate major features.

---

## Feature A: Title

Description of what this feature does and why.

Key implementation details:
- Point 1
- Point 2

---

## Feature B: Title

...

Section 4: Files Changed

Group files by category using collapsible sections:

## Files Changed

<details>
<summary>Core modules (click to expand)</summary>

- `path/to/file1.py` - Brief description
- `path/to/file2.py` - Brief description

</details>

<details>
<summary>Tests (click to expand)</summary>

- `tests/test_file1.py` - What it tests
- `tests/test_file2.py` - What it tests

</details>

Categories to consider:

  • Core modules / Services
  • API / Views / Routes
  • Models / Migrations
  • Tests
  • Configuration / Settings
  • Documentation

Section 5: How to Test

Provide both automated and manual testing instructions:

## How to Test

```bash
# Run all related tests
.bin/pytest path/to/tests/ -v
```

### Manual Testing

1. **Test scenario A**: Step-by-step instructions
2. **Test scenario B**: Step-by-step instructions

Section 6: Breaking Changes / Notes

Always include a section for special considerations:

## Notes

- **No Migrations**: This PR has no schema changes.

Or for PRs with important notes:

## Breaking Changes

- **API Change**: The `/api/endpoint` now returns X instead of Y.
- **Config Required**: Set `NEW_ENV_VAR` before deploying.

## Deploy Steps

1. Add environment variable `NEW_VAR=value`
2. Run migrations
3. Deploy code

When to Use Each Element

Scenario Use
3+ distinct features Summary table
Conditional logic ASCII decision tree
Multi-step process Box diagram or Mermaid
5+ files in a category Collapsible details
Test commands exist Code block with commands
Manual testing needed Numbered step list
Schema changes Explicit migration section
Breaking changes Dedicated callout section

Common Patterns

Feature Flag Pattern

## Feature Flag

Controlled by `FEATURE_FLAG_NAME` (default: `False`).

When enabled:
- Behavior A
- Behavior B

When disabled:
- Falls back to original behavior

Migration Pattern

## Migrations

| Migration | Description | Reversible |
|-----------|-------------|------------|
| `0001_add_field.py` | Adds `new_field` to Model | Yes |
| `0002_backfill.py` | Backfills existing rows | Yes (data loss) |

### Rollback Plan

1. Revert code deployment
2. Run `./manage.py migrate app_name 0000_previous`

API Change Pattern

## API Changes

### New Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v2/resource` | Fetches resource with new format |

### Modified Endpoints

| Endpoint | Change |
|----------|--------|
| `GET /api/v1/old` | Now returns `new_field` in response |

### Deprecated

- `GET /api/v1/legacy` - Use `/api/v2/resource` instead

Anti-Patterns to Avoid

  1. Wall of text – Use formatting (tables, lists, diagrams) instead of paragraphs.

  2. Vague descriptions – "Various bug fixes" tells reviewers nothing. Be specific.

  3. Missing test instructions – Always include how to verify the changes.

  4. Buried breaking changes – Put them in a dedicated, visible section.

  5. Listing every file – Use collapsible sections and group by purpose.

  6. No visual aids for flows – If you need more than 2 sentences to explain a flow, use a diagram.

  7. Describing only the latest commit – The PR description should cover ALL commits and changes in the branch.


References

Output

When this Skill generates a PR description, it should:

  1. Gather all context first using the commands above.
  2. Analyze ALL changes – not just the latest commit.
  3. Output the full markdown for the PR description.
  4. Offer to update the PR directly using gh pr edit if a PR exists, or create one using gh pr create if not.
  5. Be ready to iterate based on user feedback.

The description should be copy-paste ready for GitHub.

Compatibility Notes

This Skill is designed to work with both Claude Code and OpenAI Codex.

  • Claude Code: install the corresponding plugin and use its slash commands (see plugins/pr-description-writer/commands/).
  • Codex: install the Skill directory and invoke name: pr-description-writer.

For installation, see this repo's README.md.