PR Review Skill Skill | Agent Skills

PR Review Skill

This skill provides a structured approach to reviewing pull requests using parallel specialized agents for thorough coverage, with confidence scoring to minimize false positives.

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.

Review Workflow

Step 1: Pre-Review Validation

Before starting, launch a haiku agent to check if review should proceed:

Check if any of the following are true for the PR:
- The PR is closed
- The PR is a draft
- The PR is trivial (automated, obviously correct single-line change)

If any condition is true, stop and explain why.

If validation fails, do not proceed with the review.

Step 2: Gather Context

Launch two haiku agents in parallel:

Agent A - PR Summary:

Fetch PR details using: uv run scripts/gh_pr.py files owner/repo <number>
If there's a linked issue, fetch it: uv run scripts/gh_pr.py issue owner/repo <issue>
Return a brief summary of:
- What the PR does
- Files changed
- Author's stated intent — based on code and eventual linked issue

Agent B - Guidelines Discovery:

Find all relevant guideline files:
- Root CLAUDE.md (if exists)
- CLAUDE.md files in directories containing modified files
- Any project-specific style guides

Return the file paths and key rules that apply to changed files.

Step 3: Parallel Review Agents

Launch 4 specialized agents in parallel to review the changes. Each agent should receive:

PR title and description
Relevant guideline summaries (from Step 2)
The diff (via uv run scripts/gh_pr.py files owner/repo <number> --raw)

Agent 1: Bug Hunter (opus) See agents/bug-hunter.md. Focus on actual bugs and security issues.

Agent 2: Bug Hunter (opus) Same as Agent 1, run twice for coverage. Different agents may catch different issues.

Agent 3: Guideline Compliance (sonnet) See agents/guideline-compliance.md. Check CLAUDE.md and project convention adherence.

Agent 4: Error Handling Auditor (sonnet) See agents/error-handling-auditor.md. Hunt for silent failures and poor error handling.

CRITICAL: We only want HIGH SIGNAL issues:

Objective bugs that will cause incorrect behavior at runtime
Clear, unambiguous guideline violations with quoted rules
Silent failures that hide errors from users

We do NOT want:

Subjective concerns or suggestions
Style preferences not explicitly required
Potential issues that "might" be problems
Anything requiring interpretation or judgment

Step 4: Issue Validation

For each issue found with confidence >= 80, launch a validation subagent:

See agents/issue-validator.md. The validator independently verifies:

Bug reports are real (trace code, check for defensive handling)
Guideline violations actually apply (rule exists, no exceptions)
The severity assessment is accurate

Use opus subagents for bug validation, sonnet for guideline validation.

Step 5: Filter Results

Only keep issues that:

Had original confidence >= 80
Were validated in Step 4
Are not duplicates

This gives us our final list of high-signal issues.

Step 6: Post Review

If NO issues found:

Post a summary comment (if requested):

gh pr comment <number> --body "[AUTOMATED]

## Code Review

No issues found. Checked for bugs, guideline compliance, and error handling."

If issues found:

Use the batched review workflow to post all comments at once.

The Core Standard

Approve changes that improve code health, even if imperfect.

The goal is continuous improvement, not perfection
Don't block progress over minor issues - use "Nit:" prefix for non-blocking suggestions
Reject only when the change worsens overall code health or is fundamentally unwanted

Decision Hierarchy

When opinions conflict:

Technical facts and data override opinions
Style guides are authoritative
Design decisions require principle-based reasoning, not preference
Consistency with existing code (when it maintains health)

What to Look For

Design

Is the overall architecture sound?
Do code interactions make sense?
Does this belong here, or in a library/different module?
Does it integrate well with existing systems?

Architectural Consistency

Identify existing abstractions - What patterns does this codebase already have?
Check for pattern reuse - Is new code following established patterns or reinventing them?
Look for duplicated abstractions - Is the PR reimplementing existing helpers?
Look for useless abstractions - Is complexity being added unnecessarily?

Key question: "How do similar features in this codebase solve this problem?"

Functionality

Does the code do what the author intended?
Watch for: edge cases, race conditions, concurrency bugs

Complexity

Can you understand the code quickly?
Is it over-engineered for hypothetical future needs?
Principle: Solve the problem that exists now

Tests

Are there appropriate tests?
Will tests actually fail when the code breaks?
Are test cases meaningful, not just coverage padding?

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

Specialized Agents Reference

Additional agents available for targeted analysis:

Test Analyzer

See agents/test-analyzer.md. Use when:

PR adds significant new functionality
You want to verify test coverage quality
User asks about test thoroughness

Full Agent List

| Agent | Focus | Model | When to Use | |-------|-------|-------|-------------| | bug-hunter | Bugs & security | opus | Default parallel review | | guideline-compliance | CLAUDE.md adherence | sonnet | Default parallel review | | error-handling-auditor | Silent failures | sonnet | Default parallel review | | test-analyzer | Test coverage | sonnet | On request or for new features | | issue-validator | Verify findings | inherit | Validation step |

Scripts Reference

This skill includes Python scripts in scripts/ that wrap GitHub API operations. Run them with uv:

Available Commands

| 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

Posting the Code Review

Workflow Overview

Reviews are posted in a single batch to avoid spamming notifications. During the review process, 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 During Review

Edit the JSON file to add comments from validated issues:

{
  "path": "src/utils/parser.ts",
  "line": 42,
  "side": "RIGHT",
  "body": "[AUTOMATED] This catch block swallows all exceptions without logging. Unexpected errors will be silently ignored.\n\nConfidence: 92/100"
}

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 (include confidence score)

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

Step 6: Cleanup

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

Review Checklist (Quick Reference)

[ ] PR description is clear and links to relevant issue
[ ] Design is sound and appropriate for the codebase
[ ] New code extends existing abstractions rather than duplicating them
[ ] Follows patterns established by similar code in the codebase
[ ] Code does what it claims to do
[ ] Edge cases and error conditions handled
[ ] No over-engineering or unnecessary complexity
[ ] Tests are present and meaningful
[ ] Naming is clear and consistent
[ ] Comments explain why where needed
[ ] Style guide followed
[ ] Documentation updated if user-facing
[ ] No security vulnerabilities introduced
[ ] No silent failures in error handling

Replying to Existing Comments

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

Resolving Comment Threads

# 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

Quick Reference: Script Commands

| Action | Command | |--------|---------| | Fetch issue details | uv run scripts/gh_pr.py issue owner/repo 42 | | Get PR files & diff | uv run scripts/gh_pr.py files owner/repo 123 | | Get existing review comments | uv run scripts/gh_pr.py comments owner/repo 123 | | Get unresolved comments only | uv run scripts/gh_pr.py comments owner/repo 123 --unresolved | | Get PR reviews | uv run scripts/gh_pr.py reviews owner/repo 123 | | 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 /path/to/review.json | | Reply to comment | uv run scripts/gh_pr.py reply owner/repo 456 "message" | | Resolve thread | uv run scripts/gh_pr.py resolve owner/repo 123 --comment-id 456 | | Get commit SHA | uv run scripts/gh_pr.py head owner/repo 123 | | Create worktree | uv run scripts/gh_pr.py checkout owner/repo 123 | | Remove worktree | uv run scripts/gh_pr.py cleanup owner/repo 123 |

Agent Skills: PR Review Skill

Skill Files