How to use the PR Check Loop agent skill (prcheckloop)

What an agent skill is and what prcheckloop makes the agent do

An agent skill is a folder of instructions, packaged with a SKILL.md file, that an AI coding agent loads when a request matches the skill's description. prcheckloop is one such skill. Its SKILL.md describes a repair loop for GitHub PR checks.

Once installed, the agent reads the check results for the PR's latest head commit, looks at logs for failed checks, fixes problems in the code when it can, pushes the changes, and waits for the checks to run again. It repeats this until all checks are green, a blocker remains after reasonable repair effort, or the maximum number of iterations (default 5) is reached.

• Works only on the latest PR head SHA and ignores failing checks from older commits
• Classifies each failure as a code problem, a lint, type or build mismatch, a flake, an external service failure, or a missing secret or permission
• Reruns a failed job once without code changes, and does not loop on reruns
• Stops and writes a blocker report when the problem is outside the code

Install the prcheckloop skill

Download the prcheckloop ZIP from this page. The skill is distributed as a ZIP that contains SKILL.md. You can install it in one of three ways, depending on where you want the agent to find it.

For a personal install across all your projects, unzip the download into ~/.claude/skills/ so the skill folder sits there. For a single project, unzip it into the .claude/skills/ folder inside that project's repository. If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ inside the repository
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

prcheckloop depends on several tools being present and set up. The skill stops early if GitHub CLI is not authenticated, if the branch has no PR, or if the repository is not hosted on GitHub, so it is worth checking these first.

• GitHub CLI (gh), authenticated with access to the repository
• git, with push access to the PR branch
• jq, used to parse JSON output
• Network access to GitHub
• A GitHub repository. GitLab and other non-GitHub hosts are out of scope and the skill says to stop and use check-pr instead

Trigger the skill with a natural request

You do not need a special command. The skill's description says to use it when a PR still has failing or pending checks after review fixes, including after greploop. Describe the situation in plain language and name the PR if you have more than one open.

You can optionally give a PR number. If you do not, the skill detects the PR for the current branch. It also accepts a maximum iteration count if you want fewer or more passes than the default of 5.

• 'My PR still has red checks after the review fixes. Get CI green.'
• 'Keep working on PR 412 until the GitHub checks pass, and tell me what blocks it if they can't.'
• 'The lint job failed on my branch after I addressed the review. Fix it and push.'
• 'Run prcheckloop on this branch with a maximum of 3 iterations.'

What the loop does on each pass

Each pass inventories checks for the current head SHA, waits for checks that are still running, and then investigates failures. For GitHub Actions failures, the skill lists runs for that commit and reads the failed logs. It then classifies each failure and acts on it. Code and test regressions are reproduced locally and fixed. Lint, type and build mismatches are fixed by running the matching local command from the workflow.

After a fix, the skill makes a logical commit, pushes, refreshes the head SHA, and starts the inspection again. The loop is complete only when the remote checks for the new head SHA are green. Failures that need something outside the code, such as a missing secret, a permission gap, a branch protection name mismatch, or an external status app outage, are escalated with the PR URL, head SHA, failing check names, details URLs and a suggested next action.

• Flake or transient infra issue: rerun once only if the evidence supports flakiness
• External service failure: escalate with the details URL and owner guess
• Missing secret, permission or branch protection issue: escalate immediately

Safety notes: scripts, network and pushes

prcheckloop runs scripts and uses the network. Its commands call GitHub through the gh CLI and GraphQL, read workflow logs, and run git push. It also runs local verification commands from your repository's workflow. Review the SKILL.md before installing if you want to see every command it can run.

The skill pushes commits to the PR branch and reruns failed jobs once. If you do not want an agent pushing or rerunning CI without review, do not use this skill on that repository, or review each push it makes.

• Runs scripts: yes
• Uses network: yes, to GitHub
• Pushes commits to the PR branch
• Reruns a failed job once without code changes

Tips for better results

Run the skill after review comments are addressed, not during them, because it focuses on CI and status checks rather than review comment cleanup. If you also need review comments handled, pair it with check-pr. If you already use greploop for review, run prcheckloop afterward, since a review tool can pass while CI is still red.

Give the agent a clean branch with a PR open and make sure your local gh login has access to the repository before you start. Read the blocker report at the end rather than rerunning the skill blindly, because escalations usually need a person with secret or permission access.

• Use it after greploop, not as a replacement for review
• Expect pending checks to be polled every 15 to 30 seconds
• Draft PRs are detected but the skill does not say it treats them differently