pr-improver skill
✓ OfficialRuns an autonomous review-and-fix loop over branch changes until a pull request review returns zero critical or major findings.
- GitHub stars
- 8,136
- Files
- 1
- Last commit
- Nov 11, 2026
- License
- CC-BY-SA-4.0
- Allowed tools
- 6
What does the pr-improver skill do?
pr-improver runs an autonomous review-and-fix loop over branch changes until a pull request review returns zero critical or major findings.
Summary generated from the skill's SKILL.md.
About the pr-improver skill
Developers who want to ensure their code meets quality standards before submitting a pull request can use this tool to automate the refinement process. It operates by running an autonomous loop that pairs a reviewer with a fixer subagent, iterating over the changes in a specific branch until no critical or major issues remain. The process is intelligently scoped to the directories affected by the branch diff, ensuring that fixes like adding new tests are included without affecting the entire repository.
To function, the skill relies on the Workflow tool to execute an improve.js script and requires an installed PR-review skill, such as pr-review-toolkit:review-pr, to act as the judge. It uses Bash, Glob, and TaskOutput tools to manage the environment and report progress. Unlike a standard one-time review, this skill manages a continuous cycle of feedback and correction, maintaining a ledger of findings and providing clear status updates if the process hits a maximum round limit or requires human intervention due to non-convergence.
What an agent can do with it
- 1Automate branch cleanupClean up the changes on your current branch before opening a pull request.
- 2Handle complex review escalationsProvide a human decision to a loop that has stopped because it cannot resolve recurring findings.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the pr-improver skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the pr-improver skill in Plugin
/plugin marketplace add trailofbits/skills /plugin install code-improver@trailofbits
Install the pr-improver skill in Claude Code
~/.claude/skills/pr-improver/SKILL.md
$ npx degit trailofbits/skills/plugins/code-improver/skills/pr-improver ~/.claude/skills/pr-improverInstall the pr-improver skill in Claude Code (project)
.claude/skills/pr-improver/SKILL.md
$ npx degit trailofbits/skills/plugins/code-improver/skills/pr-improver .claude/skills/pr-improverInstall the pr-improver skill in Codex
~/.agents/skills/pr-improver/SKILL.md
$ npx degit trailofbits/skills/plugins/code-improver/skills/pr-improver ~/.agents/skills/pr-improverInstall the pr-improver skill in Gemini CLI
~/.gemini/skills/pr-improver/SKILL.md
$ npx degit trailofbits/skills/plugins/code-improver/skills/pr-improver ~/.gemini/skills/pr-improverInstall the pr-improver skill in Claude.ai
npx degit trailofbits/skills/plugins/code-improver/skills/pr-improver pr-improver && zip -r pr-improver.zip pr-improver # claude.ai → Customize → Skills → + → Create skill → Upload a skill → pr-improver.zip
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletrailofbits/skills/plugins/code-improver/skills/pr-improver is public and reachablegithub.com/trailofbits/skills/tree/HEAD/plugins/code-improve ↗Pass
- Open source license (OSI)CC-BY-SA-4.0 is not OSI-approvedspdx.org/licenses/CC-BY-SA-4.0.html ↗Finding
- Commit or release in the last yearLast commit 2026-11-11github.com/trailofbits/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/trailofbits/skills/blob/HEAD/plugins/code-improve ↗Pass
- Pre-approved tools are scopedBash lets the agent run any shell command without askinggithub.com/trailofbits/skills/blob/HEAD/plugins/code-improve ↗Finding
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 130 linesgithub.com/trailofbits/skills/blob/HEAD/plugins/code-improve ↗Pass
SKILL.md
View on GitHubPR Improver
Improve the current branch by running /code-improver:improve — a dynamic workflow that
loops a PR reviewer and a fixer subagent over the branch's changes until a review
reports zero critical/major findings. The loop, its ledger, and its guards live in the
workflow; this skill derives the scope from the branch diff and relays the outcome.
Starting the loop
The user provided: $ARGUMENTS (if empty, take base branch and preferences from the
conversation).
1. Resolve the branch and its change surface
- Repo root:
git rev-parse --show-toplevel. Fail loudly outside a repository. - Base: the argument if given, else the repository's default branch
(
git symbolic-ref refs/remotes/origin/HEAD→ its short name, falling back tomain). Refuse to run when the current branch IS the base — there is no diff to improve. - Changed files:
git diff --name-only <base>...HEAD. If empty, say so and stop. - Scope: the changed files' directories, widened — per-file globs are too tight
(PR fixes legitimately add tests next to changed code). Map each changed file to its
repo-relative directory glob
<dir>/**(**at the repo root only if files at the root changed), then deduplicate and drop globs covered by another.
2. Resolve the loop script
Resolve improve.js from this SKILL.md's installed location
to an absolute path and confirm the file exists. Its plugin directory is pluginRoot.
Use this exact plugin copy; if the file is missing, stop.
3. Invoke the workflow
Run it with the Workflow tool, {scriptPath: "<the path from step 2>", args: {...}}:
{
"target": "<repo root>",
"reviewer": {
"kind": "skill",
"name": "pr-review-toolkit:review-pr",
"notes": "Review the working tree's changes against <base> as a pull request: correctness, tests, error handling, and the review dimensions the skill prescribes."
},
"scope": ["<derived-dir-glob>/**"],
"pluginRoot": "<the plugin directory from step 2>",
"maxRounds": 5
}
reviewer— the default above requires thepr-review-toolkitplugin. When the user names a different PR reviewer (skill or agent), use it, with kind set accordingly.maxRoundsonly if the user asked for a different cap.pluginRootis the resolved plugin directory from step 2, for the metrics collector.finalizedefaults are right for PRs: no version bump unless the branch sits inside a plugin, narration strip and docs pass on.decisiononly on continuation (below).
The loop's baseline snapshot is the tree at loop start — its scope guard protects the branch's uncommitted work; the PR's own commits are what the reviewer reviews.
The workflow runs in the background and needs no babysitting: it reviews, fixes, re-reviews, checks scope after every fix round, and can only complete on a clean review. It never commits; all changes stay in the working tree.
If the Workflow tool is unavailable or denied, stop and say so. Do not improvise the loop inline with direct edits — the ledger, scope guard, and escalation guarantees live in the workflow, and an inline imitation has none of them.
If the result is halted: "reviewer-unavailable", relay it and stop. The reviewer
is not installed in this session; tell the user which plugin provides it (the default
needs pr-review-toolkit) and re-run after installing. Do not review the branch
yourself.
Do not end your turn while the loop is running. The Workflow tool returns a task id immediately; the result comes later. In an interactive session the completion notification re-invokes you — wait for it. In a non-interactive run (scripted, CI, eval) there is no later turn: stopping abandons the loop mid-round, so after launching, poll the task (TaskOutput with the returned task id, or sleep-and-recheck) until it completes, then relay the result. A session that answers "the loop is running, I'll report later" has lost the run.
Relaying the result
The workflow returns a structured result. Report it honestly — the distinctions matter:
converged: true— the last action was a review with zero critical/major findings. Report rounds used, remaining minor findings (open_minor_count), and the artifact paths (ledger_path,metrics).capped: true— the fix budget ran out and the FINAL review still found blocking issues. Say plainly: capped, NOT converged, and listopen_blocking. Do not present this as success.escalation— the loop detected it was not converging (recurring findings, non-decreasing counts, or a fix relocating a problem). Relay the escalation message and finding ids to the user: this needs a design decision, not more rounds.halted— a guard fired (scope violation, unregistered new files, a dead or unavailable reviewer, or a finalize pass whose own edits failed the check that follows it). Relay the paths inviolations/new_untracked_files, the sites infinalize_regressions, and the notes.notesalways travel with the result — surface them; they include loud warnings such as "a git repository was initialized".
Continuing after an escalation
The loop stops on escalation by design. When the user decides, start a fresh run with the same args plus:
{ "decision": "<the user's ruling, verbatim>" }
The new run reloads the on-disk ledger, so every finding, rejection, and verdict carries over — rounds restart, re-derivation does not.
To stop a running loop, stop the workflow task (TaskStop); the ledger on disk is current to the last round and a re-run resumes from it.
When NOT to use
- One-time review: run the PR-review skill directly; the loop's value is iteration
- A skill: use the
skill-improverentry — it wires the right reviewer - Unpushed exploratory work: review-and-fix loops harden a diff; while the shape is fluid, manual iteration gives more control
Files in this skill
1pr-improver skill questions
How do I install the pr-improver skill in Claude Code?
Run npx degit trailofbits/skills/plugins/code-improver/skills/pr-improver ~/.claude/skills/pr-improver. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the pr-improver skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What happens if the improvement loop reaches its maximum number of rounds?
If the fix budget is exhausted and the final review still has blocking issues, the process is reported as 'capped' rather than 'converged'.
Does this skill commit changes to my repository?
No, the skill does not commit; all changes made during the improvement loop remain in your working tree.