ai-pr-review Skill | Agent Skills

ai-pr-review

Description: AI-powered pull request review with inline comments, severity classification, acceptance criteria verification, and optional fix-and-verify loop

Category: Code Quality Assurance / Governance

Complexity: High (multi-step review workflow + GitHub API integration)

Purpose

Perform comprehensive AI-powered PR reviews following the governance workflow defined in governance/AI_PR_Review/. The skill:

Fetches PR diff and metadata
Verifies linked issue acceptance criteria (when applicable)
Analyzes code for bugs, security issues, performance problems
Posts formal GitHub reviews with inline comments
Applies appropriate PR labels
Optionally enters fix-and-verify loop for REQUEST_CHANGES

Capabilities

1. PR Analysis

Diff parsing: Analyze unified diff for code changes
Context reading: Read full source files for deeper understanding
Metadata extraction: PR title, body, linked issues, labels, reviewers

2. Code Review Focus Areas

Bugs: Logic errors, off-by-one, null/None handling
Security: Injection, credential leaks, auth bypass, OWASP Top 10
Performance: N+1 queries, unbounded loops, memory leaks
Error handling: Bare except, swallowed exceptions, missing retries
Type safety: API contract violations, missing type hints

3. Severity Classification

| Severity | Definition | Review Event | |:---------|:-----------|:-------------| | Critical | Security vulnerabilities, data loss, crashes | REQUEST_CHANGES | | Medium | Bugs, missing error handling, resource leaks | REQUEST_CHANGES or COMMENT | | Low | Minor improvements, best practices | COMMENT |

4. Linked Issue Verification

Parse PR body for Closes #N, Fixes #N, Resolves #N
Fetch issue acceptance criteria
Verify each criterion against PR changes
Include verification table in review output

5. Review Output

Formal GitHub Review: Inline comments in "Files changed" tab
Summary Comment: Visibility in PR conversation
Conclusion Comment: Merge decision with JSON metadata
PR Labels: ai:review-passed or ai:review-failed
Issue Cross-post: Review record on linked issue (audit trail)

6. Fix-and-Verify Loop (On-Demand)

Checkout PR branch
Apply fixes to identified findings
Commit with Co-Authored-By attribution
Push and wait for CI
Re-review (max 3 iterations)

Review Workflow

graph TD
    A[Start Review] --> B[Fetch PR Diff + Metadata]
    B --> C{Linked Issue?}
    C -->|Yes| D[Verify Acceptance Criteria]
    C -->|No| E[Note Missing Issue Link]
    D --> F[Analyze Code Changes]
    E --> F

    F --> G{Findings?}
    G -->|Critical/Medium| H[REQUEST_CHANGES]
    G -->|Low Only| I[COMMENT]
    G -->|None| J[APPROVE]

    H --> K{Fix Mode Enabled?}
    K -->|Yes| L[Fix-and-Verify Loop]
    K -->|No| M[Post Review + Conclusion]

    L --> N[Apply Fixes]
    N --> O[Commit & Push]
    O --> P[Wait for CI]
    P --> Q[Re-Review]
    Q --> R{All Fixed?}
    R -->|Yes| J
    R -->|No, Iteration < 3| L
    R -->|No, Iteration = 3| S[Escalate to Human]

    I --> M
    J --> M
    S --> M

    M --> T[Apply PR Label]
    T --> U[Cross-post to Issue]
    U --> V[Review Complete]

Usage Instructions

Basic PR Review

Review PR #<NUMBER> following the AI PR Review workflow.

The agent will:

Fetch PR diff and metadata using gh CLI
Analyze code changes
Post formal review with inline comments
Post conclusion comment
Apply ai:review-passed or ai:review-failed label

Review with Issue Verification

Review PR #<NUMBER> and verify it against linked issue #<ISSUE>.

Adds acceptance criteria verification to the review output.

Review with Fix-and-Verify

Review PR #<NUMBER> with fix-and-verify enabled.

If REQUEST_CHANGES is posted, the agent will attempt to fix findings and re-review (up to 3 iterations).

Manual Trigger Example

# Using gh CLI directly
gh workflow run ai-pr-review.yml \
  --field pr_number=42 \
  --field model=sonnet

Severity Tag Format

Inline comments use severity tags in the body:

**[Critical]** SQL injection vulnerability in user query.

Suggested fix:
```python
# Use parameterized queries instead of string concatenation
cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))


```markdown
**[Medium]** Bare `except` swallows all exceptions including KeyboardInterrupt.

```python
# Replace with specific exception handling
except Exception as e:
    logger.error(f"Operation failed: {e}")
    raise


```markdown
**[Low]** Consider using `pathlib.Path` instead of `os.path` for path operations.

Review Event Decision Tree

Has Critical findings?
 YES → REQUEST_CHANGES
 NO
    Has Medium findings?
     YES
       Affects correctness or security?
        YES → REQUEST_CHANGES
        NO (performance/style only) → COMMENT
     NO
        Has Low findings?
         YES → COMMENT
         NO → APPROVE

Conclusion Comment Format

## Review Conclusion

**Decision**: Approved to merge

| Metric | Value |
|:-------|:------|
| Findings | 0 Critical, 0 Medium, 2 Low |
| Review event | APPROVE |
| Model | claude-sonnet-4-5 |

No blocking issues found. Code changes look correct.

---
_AI Code Review (Claude) | 2026-02-17_

<!-- AI_REVIEW_METADATA {"decision":"approved","model":"claude-sonnet-4-5","pr":42,"repo":"owner/repo","findings":{"critical":0,"medium":0,"low":2},"review_event":"APPROVE","timestamp":"2026-02-17T15:30:00-05:00"} AI_REVIEW_METADATA -->

PR Labels

| Label | When Applied | Color | |:------|:-------------|:------| | ai:review-passed | APPROVE or COMMENT with zero critical/medium | Green | | ai:review-failed | REQUEST_CHANGES | Red | | skip-ai-review | Added by user to bypass automated review | Gray |

Labels are replaced on each review (not accumulated).

Skip Patterns

The following are excluded from code analysis:

File types:

*.md, *.txt, *.json, *.toml, *.yaml, *.yml, *.lock
*.svg, *.png, *.jpg, *.jpeg, *.gif, *.ico
*.woff*, *.eot, *.ttf

Directories:

docs/, .github/, governance/
LICENSE, .gitignore, .gitmodules

Exception: Include filtered files when performing documentation-specific review.

Tool Access

Required tools:

Read: Read source code files and PR diff
Bash: Execute gh CLI commands for GitHub API operations
Grep: Search for patterns in code
Glob: Find relevant source files

Required environment:

gh CLI authenticated to GitHub
ANTHROPIC_API_KEY for Claude API access
Repository write access for posting reviews

Integration Points

With code-review Skill

Uses same severity classification
Shares analysis patterns for bugs, security, performance
Complements local code review with PR-level review

With test-automation Skill

Verifies CI checks pass before APPROVE
Identifies uncovered code paths in PR

With security-audit Skill

Shares security vulnerability findings
Coordinates on CRITICAL security issues

With trace-check Skill

Verifies traceability from PR to requirements
Checks acceptance criteria alignment

Governance Integration

Issue Label Lifecycle

| Review Outcome | Issue Label Action | |:---------------|:-------------------| | REQUEST_CHANGES (entering fix loop) | Keep ai:in-progress | | Fix loop complete, APPROVE posted | Apply ai:review-requested | | Human merges PR | (auto) → Done |

PR Label Lifecycle

| Review Event | PR Label | |:-------------|:---------| | APPROVE | ai:review-passed | | COMMENT (low-only) | ai:review-passed | | REQUEST_CHANGES | ai:review-failed |

Security Constraints

| Constraint | Detail | |:-----------|:-------| | Review authority | AI reviews are advisory; human review mandatory | | Self-review rule | PR author cannot self-review; assign different reviewer | | Commit attribution | Fix commits include Co-Authored-By: Claude <noreply@anthropic.com> | | Scope containment | Fixes only address identified findings; no unrelated changes |

Limits

| Limit | Value | |:------|:------| | Max inline comments per review | 15 | | Default cost cap per review | $1.00 USD | | Review timeout | 5 minutes | | Fix-verify iterations | 3 max |

Configuration

Repository Secrets

| Secret | Description | |:-------|:------------| | ANTHROPIC_API_KEY | Anthropic API key for Claude |

Workflow Inputs

| Input | Default | Description | |:------|:--------|:------------| | model | sonnet | Claude model (sonnet, haiku, opus) | | max-budget-usd | 1.00 | Cost cap per review |

Error Handling

| Scenario | Behavior | |:---------|:---------| | Empty or trivial diff | Skip review, exit 0 | | Inline comments get 422 | Retry with summary-only review | | Review exceeds budget | Partial review posted | | Fix loop cap reached | Escalate to human reviewer | | CI failure after fix | Do not APPROVE; post COMMENT with details |

Success Criteria

Zero CRITICAL findings pass undetected
Review posted within 5 minutes
Inline comments reference correct line numbers
Conclusion comment includes valid JSON metadata
PR labels applied correctly
Issue cross-post created (when linked issue exists)

Notes

Automated reviews trigger on pull_request events
Manual reviews invoked via /ai-pr-review command or workflow dispatch
Reviews are advisory; human approval still required
Fix-verify loop requires explicit enablement

Agent Skills: ai-pr-review

Install this agent skill to your local

Skill Files