coder-agents-review - SKILL.md Agent Skill

name: coder-agents-review description: "Use this skill when a repository already has an open pull request and you need to run the Coder Agents Review loop: request review with `/coder-agents-review` when needed, wait for feedback from the `coder-agents-review` GitHub app, fix issues, and repeat until the app comments `approved`."

Coder Agents Review Loop

Goal

Drive an existing pull request until the GitHub app coder-agents-review has approved the current work.

The loop is:

if the PR has no existing coder-agents-review review, comment, or pending trigger, post /coder-agents-review
wait for coder-agents-review to respond
fix actionable issues with the smallest safe diff
validate and push
request another review with /coder-agents-review
repeat until the app comments approved

Definition of done

Only stop when all of these are true:

the latest coder-agents-review response for the current work says approved (case-insensitive), or is a GitHub APPROVED review from that app
there are no unresolved actionable coder-agents-review review threads left from the latest feedback, unless a policy or permission blocker prevents resolution and you reported it
local validation relevant to the touched code has been run after the last changes
the branch has been pushed

If you stop early, say exactly why.

Non-negotiable behavior

Inspect the PR before posting anything.
If the PR has no review or comment from coder-agents-review and no pending trigger comment, post a top-level PR comment with the exact body /coder-agents-review.
If coder-agents-review activity is already present, start from that feedback instead of posting a duplicate trigger immediately.
After every fix push, post /coder-agents-review again.
Wait indefinitely for the app's first response after each request. Do not treat silence as approval.
Fix the app's actionable feedback with the smallest reasonable diff. Avoid unrelated cleanup.
Resolve addressed app review threads if you can. If you cannot, reply with a short fix summary and report the blocker.
Never create or merge a PR unless the user explicitly asks.

Defaults and config

Use repository conventions first. Otherwise use these defaults.

PR_NUMBER: PR number to operate on. If unset, infer it from the current branch's open PR.
REVIEW_TRIGGER: exact request comment.
```
/coder-agents-review
```
REVIEW_APP_LOGIN_REGEX: default match for the app author login.
```
^coder-agents-review(\[bot\])?$
```
APPROVED_REGEX: case-insensitive match for an explicit approving status line from the app.
```
^[[:space:]>]*approved[[:space:].!]*$
```
Apply this only to individual status lines from the app response, not to arbitrary body text. Negative phrases such as not approved or cannot be approved yet are feedback, not approval.
LOCAL_VALIDATE_CMD: repo-standard validation command.
LOCAL_TEST_CMD: optional targeted validation for the touched area.
POLL_INTERVAL_SEC: default 30.
PAGE_SIZE: default 100. Use it for each GitHub pagination request, not as a cap on the total activity fetched.

If the app login does not match the default regex, discover the exact app author login from trusted GitHub activity or metadata, then match only that login. Do not guess when the evidence is unclear.

Discover PR context

Confirm GitHub auth:

gh auth status

Infer the PR number if needed:

PR_NUMBER="${PR_NUMBER:-$(gh pr view --json number --jq .number)}"
echo "$PR_NUMBER"

Get basic PR info:

gh pr view "$PR_NUMBER" --json number,title,url,headRefName,headRefOid,isDraft

Identify owner and repo:

OWNER="$(gh repo view --json owner --jq .owner.login)"
REPO="$(gh repo view --json name --jq .name)"

Collect app activity

Inspect top-level PR comments, PR reviews, and review threads. Fetch all pages before deriving review state. GitHub GraphQL connections are paginated, so a single first:100 request can miss newer review-app activity on busy PRs.

Page these connections until pageInfo.hasNextPage is false:

comments, for top-level PR comments
reviews, for PR reviews
reviewThreads, for review thread metadata
each review thread's comments, when its nested comment connection has more pages

Example page query:

gh api graphql -f query='query(
  $owner: String!
  $repo: String!
  $number: Int!
  $pageSize: Int!
  $commentsAfter: String
  $reviewsAfter: String
  $threadsAfter: String
) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $number) {
      number
      url
      headRefName
      headRefOid
      comments(first: $pageSize, after: $commentsAfter) {
        pageInfo { hasNextPage endCursor }
        nodes {
          body
          createdAt
          url
          author { login }
        }
      }
      reviews(first: $pageSize, after: $reviewsAfter) {
        pageInfo { hasNextPage endCursor }
        nodes {
          body
          state
          submittedAt
          url
          author { login }
          commit { oid }
        }
      }
      reviewThreads(first: $pageSize, after: $threadsAfter) {
        pageInfo { hasNextPage endCursor }
        nodes {
          id
          isResolved
          comments(first: $pageSize) {
            pageInfo { hasNextPage endCursor }
            nodes {
              body
              createdAt
              url
              author { login }
            }
          }
        }
      }
    }
  }
}' \
-F owner="$OWNER" \
-F repo="$REPO" \
-F number="$PR_NUMBER" \
-F pageSize="${PAGE_SIZE:-100}"

If a review thread's nested comments.pageInfo.hasNextPage is true, fetch that thread by node ID and keep paging its comments before using that thread to decide whether feedback remains unresolved.

Build these facts from the complete paginated activity set:

latest exact trigger comment with body /coder-agents-review
latest top-level comment from the review app
latest PR review from the review app
latest review-app approval signal, either a review with state APPROVED or a comment body matching APPROVED_REGEX
unresolved review threads where the latest relevant comment came from the review app

Treat the app as matched when the author login matches REVIEW_APP_LOGIN_REGEX, or when it exactly equals a discovered app login. Do not treat a substring match as sufficient.

Request rules

First request

If the PR has no review or comment from coder-agents-review, and no existing /coder-agents-review trigger comment that the app has not yet responded to, post the exact trigger comment:

gh pr comment "$PR_NUMBER" --body "/coder-agents-review"

If a trigger comment already exists but the app has not responded yet, skip posting and enter the wait loop.

Existing activity already present

If the PR already has coder-agents-review activity, do not post another trigger immediately just because the skill started.

Instead:

inspect the latest app feedback
if the latest app response is already an approval for the current work, finish
if the latest app response contains actionable feedback, fix that feedback first
after pushing fixes, post /coder-agents-review again

If you cannot confidently tell whether an old approval covers the current head SHA, do not guess. Push the intended fixes, then request a fresh review.

Wait loop

After every review request, wait until the app responds. Keep polling. Do not replace waiting with a timeout.

A minimal loop is:

while :; do
  # refresh PR comments, reviews, and review threads
  # detect app response newer than the latest request
  # break only when the app has responded or a concrete blocker occurs
  sleep "${POLL_INTERVAL_SEC:-30}"
done

A response counts when a new coder-agents-review comment or review is visible after the latest trigger comment.

Handling feedback

When the app leaves feedback:

build a worklist from unresolved app review threads and any actionable top-level app comments
classify each item as fix-now, already-satisfied, blocked, or out-of-scope
implement the smallest safe in-scope fixes
run local validation
push the branch
resolve the threads you actually fixed, or reply with a concise summary if resolution is blocked
post /coder-agents-review again
return to the wait loop

Do not widen scope for opportunistic cleanup.

Validation

Before every new review request:

run the repository's standard validation command, if available
run targeted tests for the touched area, if appropriate
fix failures before pushing

Examples:

test -n "${LOCAL_VALIDATE_CMD:-}" && eval "$LOCAL_VALIDATE_CMD"
test -n "${LOCAL_TEST_CMD:-}" && eval "$LOCAL_TEST_CMD"

Do not claim success if code changed but relevant validation did not run.

Resolving review threads

Prefer repository helpers if they exist. Otherwise resolve threads with GitHub GraphQL:

gh api graphql -f query='mutation($id: ID!) {
  resolveReviewThread(input: {threadId: $id}) {
    thread {
      isResolved
    }
  }
}' -F id="<thread_id>"

If you cannot resolve a fixed thread yourself:

leave a concise reply describing the fix
keep the thread open
report the blocker in the final summary

Completion rule

Only finish when the latest relevant app response is an approval for the current work.

A valid approval is either:

a review from the app with state APPROVED, or
a top-level app comment with an explicit approving status line that matches APPROVED_REGEX

When checking APPROVED_REGEX, split the comment body into lines and match a complete line. Do not search arbitrary prose for the word approved.

If the latest app response is anything else, keep iterating.

Final report

When the loop finishes, report:

PR number and URL
current head SHA
when /coder-agents-review was last requested
when coder-agents-review last responded
the approval evidence, review state or matching comment text
whether any app threads remain unresolved, and why
what validation was run
any blockers if the loop ended early

Operating rules

Never post duplicate trigger comments on the same head when the app is already reviewing or has already left feedback you have not handled yet.
Never treat silence as approval.
Never claim success without explicit app approval evidence.
Never accept review-app activity from a substring author match.
Never ignore unresolved actionable app feedback.
Never skip validation after making changes.
Never derive approval or completion from unpaginated PR activity.
Prefer gh and repo-native helpers over manual browser work.