aspiers/ai-config / .agents/skills/describing-prs
describing-prs
VerifiedGenerates a pull request description for the current branch and writes it as Markdown to .git/magit/posts/new-pullreq for magit-forge. Use when the user asks for a PR description, PR summary, or write-up of what a branch changes, or is preparing to open a pull request.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.4 KB |
| scripts/find-merge-base.pyexecutable | script | 8.7 KB |
SKILL.md
View on GitHub---
name: describing-prs
description: >-
Generates a pull request description for the current branch and writes it as
Markdown to .git/magit/posts/new-pullreq for magit-forge. Use when the user
asks for a PR description, PR summary, or write-up of what a branch changes,
or is preparing to open a pull request.
allowed-tools: Bash(~/.agents/skills/describing-prs/scripts/find-merge-base.py:*)
---
# PR Description Generator
Generate a well-structured PR description for the current feature branch.
## When to Use This Skill
Use this skill when:
- Preparing to create a pull request
- Needing a PR description for the current branch
- Integrating with magit-forge for PR creation
## Process
1. **Determine the base branch**
Run the helper script to find the base branch:
```bash
BASE=$(~/.agents/skills/describing-prs/scripts/find-merge-base.py)
```
The script outputs a branch name (e.g., `origin/main`) that represents
the base branch for comparison. It handles cases where you branched
from another feature branch, not just main/master.
**Options**:
- `--fetch`: Fetch latest remote refs before determining base branch
- `--debug`: Show how the base branch is determined
**Strategy** (implemented in the script):
- Try `@{upstream}` first (the current branch's configured upstream)
- Try `origin/HEAD` (the remote's default branch)
- Fall back to common defaults: `origin/main`, `origin/master`, `origin/develop`
- If neither works, find the closest remote branch by commit distance
2. **Gather context about the branch**
Using the base branch found above:
```bash
git branch --show-current
git log --oneline <base-branch>..HEAD
git diff --no-ext-diff <base-branch>..HEAD --stat
git diff --no-ext-diff <base-branch>..HEAD
```
3. **Analyze the changes**
- Identify the purpose of the changes
- Group related commits by theme
- Note any breaking changes or important considerations
4. **Generate the PR description**
Write a Markdown file with:
- **Title**: A concise summary (will be used as PR title)
- **Summary**: 2-3 sentences explaining the overall purpose
- **Changes**: Bullet points of key modifications
- **Testing**: How the changes were tested (if applicable)
- **Notes**: Any reviewer notes, breaking changes, or follow-up items
5. **Write to the output file**
Create the directory and write the description:
```bash
mkdir -p .git/magit/posts
```
Write Markdown content to `.git/magit/posts/new-pullreq`
## Output Format
The generated file should follow this structure:
```markdown
# <PR Title>
## Summary
<Brief explanation of what this PR accomplishes and why>
## Changes
- <Key change 1>
- <Key change 2>
- ...
## Testing
<How changes were tested, or "N/A" if not applicable>
## Notes
<Any additional context for reviewers, breaking changes, or follow-up work>
```
## Formatting Guidelines
- Wrap all symbols, variables, function names, file paths, and code references
in backticks (e.g., `myFunction`, `CONFIG_VALUE`, `src/utils.ts`)
- Use fenced code blocks for multi-line code snippets
- Keep bullet points concise and scannable
## Important Notes
- The file path `.git/magit/posts/new-pullreq` is used by magit-forge
- Always overwrite the existing file if present
- Keep the description concise but informative
- Focus on the "why" more than the "what" (the diff shows the "what")
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |