# pr-description

> Use this skill when creating or updating PR descriptions. Provides detailed guidelines for writing clear, comprehensive pull request descriptions with proper Summary and Testing sections.

- Skill: `thanakijwanavit/pr-description` (Agent Skill)
- Install (CLI): `npx skillmds add thanakijwanavit/pr-description`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thanakijwanavit/pr-description/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thanakijwanavit (https://skillmd.com/u/thanakijwanavit)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/thanakijwanavit/pr-description

---


# PR Description

Write clear, comprehensive pull request descriptions following these guidelines.

## PR Description Structure

### Required Sections

Every PR must have:

**## Summary**

- Opening paragraph explaining the high-level goal and motivation
- Bullet points describing what specifically changed
- **Keep it proportional**: Small changes deserve concise descriptions; large changes deserve detailed breakdowns
- Focus on concrete details, not vague descriptions
- Use specific values, file paths, and configuration details

**## Testing**

- How changes were validated
- Commands run to verify correctness
- Manual testing performed
- Screenshots/videos for UI changes

### Optional Sections (use when relevant)

**## Key Changes** - For complex PRs, break down changes by component, environment, or logical grouping

**Technical Detail Sections:**

- **## Deployment Considerations** - Pre/post-deployment steps required
- **## Rationale** - Explain design decisions and "why" questions
- **## Behavior** - Describe how the system behaves after changes
- **## Migration** - Steps to transition from old to new
- **## Configuration** - New settings or environment variables
- **## Next Steps** - Follow-up work or monitoring needed

## Writing Guidelines

### Summary Section

**Match description length to change scope:**

- Small, focused changes (1-3 files, simple logic) → 1 paragraph + 2-4 bullets max
- Medium changes (multiple components, some complexity) → 1 paragraph + grouped bullets
- Large changes (major refactoring, new systems) → Detailed breakdown with subsections

**Opening paragraph:**

- Explain what problem is solved or what feature is added
- Include the "why" — business value or technical motivation
- Keep it to 1-3 sentences

**Bullet points:**

- **Be concise**: Convey core meaning with minimal words
- Be specific with values, not vague descriptions
- Include inline code formatting: Use backticks for `fields`, `values`, and `file.paths`
- Group related changes under bold headers only when there are multiple distinct logical sections

### Testing Section

Document all validation performed with specific details:

- What commands were run
- What test coverage was added or modified
- What manual verification steps were taken
- Do NOT write vague statements like "Tested manually"

## Style Guidelines

**Use inline code formatting liberally** for field names, values, file paths, and commands.

**Use bold headers for subsections** to make long descriptions scannable.

**Be specific with numbers** — quote actual values, not vague descriptions.

**Explain trade-offs and decisions** — show you considered alternatives.

**Show before/after code snippets when relevant:**

- Structural improvements, API changes, logic simplification, pattern migrations
- Do NOT include for large diffs, trivial changes, or new features from scratch

## PR Footer

At the bottom of every PR description, include:

```
---
🤖 *Generated by Computer*
```