Generate comprehensive, reviewer-friendly PR descriptions with diagrams, summary tables, collapsible sections, and structured test plans.
Generates comprehensive, reviewer-friendly PR descriptions with diagrams, summary tables, and structured test plans.
/plugin marketplace add diversioteam/agent-skills-marketplace/plugin install pr-description-writer@diversiotechThis skill is limited to using the following tools:
references/gh-cli.mdUse this Skill when:
This Skill is designed to work with any repository but is especially tuned for Django/Python backends, React frontends, and infrastructure changes.
pr-description-writer to create a PR description for my current branch."pr-description-writer Skill."gh (see references/gh-cli.md).Reviewers should understand the PR in 30 seconds from the summary, then dive deeper as needed. Structure content in layers:
Use diagrams, tables, and structured formatting instead of prose where possible:
Every section should answer a reviewer's question:
Never describe only the latest commit. The PR description must reflect:
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.
For any non-trivial flow, include a visual diagram. Choose the appropriate format based on complexity:
Use for decision trees and linear flows:
## Feature Flow
```
First condition?
│
YES ──► Has prior state? ──► YES: Action A
│ └──► NO: Action B
│
NO ───► Action C
```
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]
```
Use for showing data flow or process stages:
## Data Pipeline
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Input Stage │────►│ Process Stage │────►│ Output Stage │
│ (description) │ │ (description) │ │ (description) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
For each major feature, provide a dedicated section with:
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
...
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:
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
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
| 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 |
## Feature Flag
Controlled by `FEATURE_FLAG_NAME` (default: `False`).
When enabled:
- Behavior A
- Behavior B
When disabled:
- Falls back to original behavior
## 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 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
Wall of text – Use formatting (tables, lists, diagrams) instead of paragraphs.
Vague descriptions – "Various bug fixes" tells reviewers nothing. Be specific.
Missing test instructions – Always include how to verify the changes.
Buried breaking changes – Put them in a dedicated, visible section.
Listing every file – Use collapsible sections and group by purpose.
No visual aids for flows – If you need more than 2 sentences to explain a flow, use a diagram.
Describing only the latest commit – The PR description should cover ALL commits and changes in the branch.
gh + git): references/gh-cli.mdWhen this Skill generates a PR description, it should:
gh pr edit if a PR exists, or
create one using gh pr create if not.The description should be copy-paste ready for GitHub.
This Skill is designed to work with both Claude Code and OpenAI Codex.
plugins/pr-description-writer/commands/).name: pr-description-writer.For installation, see this repo's README.md.
Expert guidance for Next.js Cache Components and Partial Prerendering (PPR). **PROACTIVE ACTIVATION**: Use this skill automatically when working in Next.js projects that have `cacheComponents: true` in their next.config.ts/next.config.js. When this config is detected, proactively apply Cache Components patterns and best practices to all React Server Component implementations. **DETECTION**: At the start of a session in a Next.js project, check for `cacheComponents: true` in next.config. If enabled, this skill's patterns should guide all component authoring, data fetching, and caching decisions. **USE CASES**: Implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, debugging cache issues, and reviewing Cache Component implementations.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.