How to use the GitHub PR Review Iteration agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file and any supporting files that an AI agent can load to follow a defined procedure. This skill is an orchestrator: it sequences the work and hands the triage and implementation steps to dedicated sub-agent instructions rather than doing everything in one pass.

Given a pull request, the loop is: fetch current review state, render and summarize it, triage review threads into an action plan, implement the actions, and re-fetch until no actionable items remain.

• Items the agent will address get a reply with a thumbs-up reaction and stay unresolved until the fix is made.
• Items not addressed in this PR get a reply with a rationale and a thumbs-down reaction, and the thread is resolved.
• Code changes are made in granular, intent-driven commits with explicit staging only (the source says it never uses git add -A or git add .).
• When a fix is complete the agent replies "Done" and resolves the thread.
• State and plan files are written to wip/reviews/<owner>_<repo>_pr-<number>/ for tracking.

Install the skill (ZIP download or Claude apps upload)

Download the skill ZIP from the directory page and unzip it. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

This skill also depends on three sibling skills (review-fetch-phase, review-triage-phase and review-implement-phase) that must live in the same parent directory as github-review-iteration. Without them the orchestrator cannot run.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills

Install the requirements

The skill needs Node.js because its scripts are .mjs files. It also needs the GitHub CLI (gh) authenticated with an account that can read and write PR review threads, and Git access to the repository with push permission.

Your AI agent runtime must support SKILL.md sub-agent delegation.

• Node.js
• GitHub CLI (gh), authenticated with an account that can read and write PR review threads
• Git repository access with push permission
• Sibling skills: review-fetch-phase, review-triage-phase, review-implement-phase
• An agent runtime that supports SKILL.md sub-agent delegation

How do you trigger the skill with a natural request?

You can ask in plain language. The skill's description is triggered by requests such as "address PR review", "triage review comments" or "iterate until review is clean".

If you prefer explicit control, the skill supports three subcommands: triage (fetch and triage into structured actions), implement (execute the triaged actions and update status), and iterate (loop triage then implement until clear, the default).

• "Address the PR review on this pull request: <PR URL>"
• "Triage the review comments on <PR URL>"
• "Iterate until the review is clean for <PR URL>"

Run it on a pull request step by step

Run the scripts from the repository root, using the full path under your skills installation. If the output directory is omitted, the skill uses wip/reviews/<owner>_<repo>_pr-<number>/ derived from the PR URL, with owner and repo lowercased.

The main canonical files are review-state.json and review-actions.json. Derived files include review-state.md, a summary, review-actions.md and an optional apply-log.json.

• Triage: the triager fetches review state and writes review-actions.json and review-actions.md.
• Implement: the implementer works through pending will_address actions, making focused commits and replying "On it", then "Done" and resolving the thread.
• Re-fetch: the loop repeats until nothing actionable is left.

Safety notes: scripts, network and GitHub writes

This skill runs scripts and uses the network. It posts replies, reactions and resolves threads on GitHub, and it makes commits on your branch. Only use it on repositories where you have push rights and where those actions are acceptable.

If gh API calls fail with TLS or certificate errors in a sandboxed shell (for example x509: OSStatus -26276), the source treats this as a sandbox certificate-store issue. Re-run those gh calls outside the sandbox. The source says not to disable TLS verification, such as with GH_NO_VERIFY_SSL or custom curl flags.

• Review the reply and resolve actions before running on a shared branch.
• Do not run it where the agent should not commit or resolve threads for you.
• Automated reviewers like CodeRabbit can bundle several findings into one review body; the triager is instructed to split these rather than dismiss them wholesale.

Tips for better results

Run the scripts from the repository root so artifacts land in the wip/ tree that .gitignore covers. If you must run from elsewhere, pass --reviews-root pointing at <repo-root>/wip/reviews.

Read review-actions.md after the triage step before implementing, so you can see each decision and its rationale.

• Start with the triage subcommand if you want to inspect decisions first.
• Keep the three sibling skills installed alongside this one.
• Use the explicit output-dir argument if you want artifacts in a specific place.