pr-review

PR Review Skill

This skill covers how to leave a PR review, not what to look for in the code. It assumes you already know which issues you want to raise and gives you the CLI commands and conventions to attach them to the right place, word them well, and post them as a single batched review.

Important: Any text comment you post must be prefixed with:

[AUTOMATED]

This is important because you are using the Github CLI with the account of your beloved human, and you want to make it clear that the comment is not coming from the human.

Writing Effective Comments

Severity Labels

• Nit: Minor issue, should fix but won't block approval
• Optional/Consider: Suggestion worth considering, not required
• FYI: Information only, no action expected

Tone

• Be kind - critique code, never the person
• Explain the reasoning behind suggestions
• Acknowledge when the author knows more than you
• Don't block progress over minor issues - use "Nit:" prefix for non-blocking suggestions

Posting the Code Review

Workflow Overview

Reviews are posted in a single batch to avoid spamming notifications. Accumulate feedback in a transient JSON file, then submit everything at once.

If you are inside the same repository as the PR, checkout the PR branch into a temporary worktree for full codebase context.

Step 1: Checkout the PR (if in same repo)

# Create a temporary worktree for the PR
WORKTREE_PATH=$(uv run scripts/gh_pr.py checkout owner/repo 123)
cd "$WORKTREE_PATH"

Step 2: Initialize Review File

# Creates /tmp/pr-review-{owner}-{repo}-{pr}.json with commit SHA
uv run scripts/gh_pr.py init-review owner/repo 123

This creates a JSON file with the structure:

{
  "owner": "anthropics",
  "repo": "claude-code",
  "pr_number": 123,
  "commit_id": "abc123def456",
  "body": "",
  "event": "COMMENT",
  "comments": []
}

Step 3: Add Comments

Edit the JSON file's comments array to attach feedback to the right file and line:

{
  "path": "src/utils/parser.ts",
  "line": 42,
  "side": "RIGHT",
  "body": "[AUTOMATED] Nit: this catch block swallows all exceptions without logging."
}

Field reference:

• path: File path relative to repo root
• line: Line number in the new file (for additions/modifications)
• side: RIGHT for new/modified code, LEFT for deleted code
• body: The comment text, prefixed with [AUTOMATED]

To find valid file/line targets, or to check what's already been discussed, use files and comments (see Scripts Reference below).

Step 4: Set the Review Verdict

Step 5: Post the Review

uv run scripts/gh_pr.py post owner/repo 123 /tmp/pr-review-owner-repo-123.json

If there are no comments to attach, post a summary comment instead:

gh pr comment 123 --body "[AUTOMATED]

## Code Review

No issues found."

Step 6: Cleanup

uv run scripts/gh_pr.py cleanup owner/repo 123

Replying to and Resolving Existing Comments

# Reply to a specific review comment
uv run scripts/gh_pr.py reply owner/repo 456 "[AUTOMATED] Response to the discussion"

# Resolve a thread by comment ID
uv run scripts/gh_pr.py resolve owner/repo 123 --comment-id 456

# Unresolve a thread by comment ID
uv run scripts/gh_pr.py resolve owner/repo 123 --comment-id 456 --unresolve

Scripts Reference

This skill includes a Python script (scripts/gh_pr.py) that wraps GitHub API operations. Run it with uv:

Usage Examples

# Fetch issue details
uv run scripts/gh_pr.py issue owner/repo 42

# Get PR files and diff
uv run scripts/gh_pr.py files owner/repo 123

# Get raw JSON for agent processing
uv run scripts/gh_pr.py files owner/repo 123 --raw

# Get unresolved review comments
uv run scripts/gh_pr.py comments owner/repo 123 --unresolved

# Initialize review file
uv run scripts/gh_pr.py init-review owner/repo 123

# Post batched review
uv run scripts/gh_pr.py post owner/repo 123 /tmp/pr-review-owner-repo-123.json