From agent-almanac
Reviews GitHub pull requests end-to-end using the gh CLI. Covers diff analysis, commit history, CI checks, and severity-leveled feedback submission.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-almanac:review-pull-requestThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Review a GitHub pull request end-to-end — from understanding the change through submitting structured feedback. Uses `gh` CLI for all GitHub interactions and produces severity-leveled review comments.
Review a GitHub pull request end-to-end — from understanding the change through submitting structured feedback. Uses gh CLI for all GitHub interactions and produces severity-leveled review comments.
owner/repo#number)Read the PR description and understand what the change is trying to accomplish.
gh pr view <number> --json title,body,author,baseRefName,headRefName,labels,additions,deletions,changedFiles,reviewDecision
PR Size Guide:
+--------+-----------+---------+-------------------------------------+
| Size | Files | Lines | Review Approach |
+--------+-----------+---------+-------------------------------------+
| Small | 1-5 | <100 | Read every line, quick review |
| Medium | 5-15 | 100-500 | Focus on logic changes, skim config |
| Large | 15-30 | 500- | Review by commit, focus on critical |
| | | 1000 | files, flag if should be split |
| XL | 30+ | 1000+ | Flag for splitting. Review only the |
| | | | most critical files. |
+--------+-----------+---------+-------------------------------------+
gh pr view <number> --json commits --jq '.commits[].messageHeadline'
gh pr checks <number>
Expected: A clear understanding of what the PR does, why it exists, how big it is, and whether CI is green. This context shapes the review approach.
On failure: If the PR description is empty or unclear, note this as the first piece of feedback. A PR without context is a review antipattern. If gh commands fail, verify you're authenticated (gh auth status) and have access to the repository.
Read the actual code changes systematically.
gh pr diff <number>
gh pr diff <number> --patch # full patch format
Expected: A set of observations covering correctness, security, performance, and quality for every meaningful change in the diff. Each observation has a severity level.
On failure: If the diff is too large to review effectively, flag it: "This PR changes {N} files and {M} lines. I recommend splitting it into smaller PRs for more effective review." Still review the highest-risk files.
Organize observations into severity levels.
Feedback Severity Levels:
+-----------+------+----------------------------------------------------+
| Level | Icon | Description |
+-----------+------+----------------------------------------------------+
| Blocking | [B] | Must fix before merge. Bugs, security issues, |
| | | data loss risks, broken functionality. |
| Suggest | [S] | Should fix, but won't block merge. Better |
| | | approaches, missing edge cases, style issues that |
| | | affect maintainability. |
| Nit | [N] | Optional improvement. Style preferences, minor |
| | | naming suggestions, formatting. |
| Praise | [P] | Good work worth calling out. Clever solutions, |
| | | thorough testing, clean abstractions. |
+-----------+------+----------------------------------------------------+
Expected: A sorted list of feedback items with clear severity levels. Blocking items have fix suggestions. The ratio should generally be: few Blocking, some Suggest, minimal Nit, at least one Praise.
On failure: If everything seems blocking, the PR may need to be reworked rather than patched. Consider requesting changes at the PR level rather than line-by-line comments. If nothing seems wrong, say so — "LGTM" is valid feedback when the code is good.
Compose the review with structured, actionable feedback.
# Post inline comments via gh API
gh api repos/{owner}/{repo}/pulls/{number}/comments \
-f body="[B] This SQL query is vulnerable to injection. Use parameterized queries instead.\n\n\`\`\`suggestion\ndb.query('SELECT * FROM users WHERE id = $1', [userId])\n\`\`\`" \
-f commit_id="<sha>" \
-f path="src/users.js" \
-F line=42 \
-f side="RIGHT"
[B], [S], [N], or [P]# Approve
gh pr review <number> --approve --body "Review summary here"
# Request changes (when blocking issues exist)
gh pr review <number> --request-changes --body "Review summary here"
# Comment only (when unsure or providing FYI feedback)
gh pr review <number> --comment --body "Review summary here"
Expected: A submitted review with clear, actionable feedback. The author knows exactly what to fix (Blocking), what to consider (Suggest), and what went well (Praise).
On failure: If gh pr review fails, check permissions. You need write access to the repo or to be a requested reviewer. If inline comments fail, fall back to putting all feedback in the review body with file:line references.
Track the review resolution.
gh pr view <number> --json reviewDecision,reviews
gh pr diff <number> # check new commits
gh pr review <number> --approve --body "All blocking issues resolved. LGTM."
Expected: Blocking issues verified as fixed. Review conversation resolved. PR approved or further changes requested with specific remaining items.
On failure: If the author disagrees with feedback, discuss in the PR thread. Focus on impact (why it matters) rather than authority. If disagreement persists on non-blocking items, yield gracefully — the author owns the code.
review-software-architecture — System-level architecture review (complementary to PR-level review)security-audit-codebase — Deep security analysis for PRs with security-sensitive changescreate-pull-request — The other side of the process: creating PRs that are easy to reviewcommit-changes — Clean commit history makes PR review significantly easiernpx claudepluginhub pjt222/agent-almanacReviews GitHub pull requests using gh CLI, analyzing diffs for code quality, security, and test coverage.
Reviews a pull request for code quality and correctness. Use when asked to review a PR or when running as an automated PR reviewer.