PR Review Skill Skill | Agent Skills

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

| Verdict | event value | When to use | |---------|---------------|-------------| | Approve | APPROVE | Code is good to merge | | Request Changes | REQUEST_CHANGES | Blocking issues must be addressed | | Comment | COMMENT | Feedback only, not blocking |

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:

| Command | Description | |---------|-------------| | files | Get PR files with status and patch info | | comments | Get review comments (supports --unresolved, --pending filters) | | reviews | List all reviews on a PR | | post | Post a batched review from JSON file | | reply | Reply to a specific review comment | | resolve | Resolve or unresolve a review thread | | head | Get the head commit SHA for a PR | | checkout | Create a worktree to review PR locally | | cleanup | Remove a PR worktree | | init-review | Initialize a review JSON file | | issue | Fetch issue details (title, description, labels, assignees) |

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

Agent Skills: PR Review Skill

Install this agent skill to your local

Skill Files