engineering / Review & improve
pr-workflow
Creates and manages pull requests — pushes the branch, writes a reviewer-focused description (why + how to verify), names the PR to match branch intent, and checks mergeability.
Put it to work.
Ask your agent to use pr-workflow, or let it load the skill when your task matches the description.
Use the pr-workflow skillInvocation syntax varies by agent. Use the skill name in your prompt, or your agent’s supported slash command.
About this skill
Create and update pull requests with consistent naming, concise reviewer-focused descriptions, and mergeability checks.
- Pushes the branch and targets the repo default base branch
- Aligns PR title with branch intent (
feat,fix,chore) - Focuses PR descriptions on why the change exists and how to verify it
Install
npx skills@latest add smeltery/skillsOr copy just this skill:
mkdir -p ~/.claude/skills/pr-workflow
curl -fsSL https://raw.githubusercontent.com/smeltery/skills/main/skills/engineering/pr-workflow/SKILL.md \
-o ~/.claude/skills/pr-workflow/SKILL.mdUsage
Use when creating a PR, editing a PR description, assigning reviewers, or checking mergeability.
Files
SKILL.md— canonical skill definition.
Read the full SKILL.md
Committing Before Pushing
Use the /git-commit skill to stage and commit any outstanding changes before pushing. Never use git commit -m with inline strings.
Pushing the Branch
git push origin <branch-name>Creating the PR
Create the PR against the repo's default branch unless directed otherwise. The default is main or master depending on the repo:
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
gh pr create --base "$DEFAULT_BRANCH" ...PR Naming
PR name should match the branch intent:
| Branch | PR Title |
|---|---|
feat/<feature-name> |
feat: feature name |
fix/<bug-name> |
fix: bug name |
chore/<task-name> |
chore: task name |
May include an issue reference: feat: feature name [AI-123]
Writing the PR Description
Before writing, gather context:
git diff "origin/${DEFAULT_BRANCH}...HEAD"— the actual changes; let these speak for themselves (useorigin/<default>not the local ref — your local copy may be stale)- Check for a plan file (e.g.
.claude/plans/,PLAN.md, or similar) — use it to understand intent, not to copy into the description - Read
.github/pull_request_template.mdand fill it out
The description should answer two questions for a reviewer:
- Why does this change exist?
- How do I verify it works?
The diff already shows what changed, so don't restate it.
Always open with a section titled Why this PR is necessary — one to three bullets on what breaks or stays missing without this, before anything else in the body. Add it even when the repo's own .github/pull_request_template.md has no equivalent heading; every other section still maps to that template as usual.
What to leave out
A PR description is not a lab report, a commit log, or an explanation of how you arrived at the solution. Strip out:
- Investigation steps ("I tried X and found Y")
- Disproved theories or dead ends
- Intermediary decisions that didn't make the final cut
- Anything that only makes sense if you were there (e.g. "the harness confirmed...")
- Self-congratulatory or hedging side commentary
If you're explaining your process rather than the change, cut it.
Test steps
In "Test steps" (or the equivalent section in your PR template), write concrete steps a reviewer can follow:
- ✅
npm test -- src/auth.test.ts— relevant tests pass - ❌ "I tested this locally and it works"
Calibration
A good description is often 3–6 lines. If you're writing more than ~10 lines of prose, you're probably over-explaining. When in doubt, cut.
Apply directly — don't draft for user review first; use gh pr edit or gh pr create with the description inline.
PR Assignment
gh pr edit <pr_number> --add-assignee @meMergeability Check
gh pr view <pr_number> --json mergeable,mergeStateStatusIf mergeable is CONFLICTING, resolve conflicts before proceeding.