Use when reviewing GitHub pull requests with gh CLI - creates pending reviews with code suggestions, batches comments, and chooses appropriate event types (COMMENT/APPROVE/REQUEST_CHANGES)
80%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./.claude/skills/github-pr-review/SKILL.mdWorkflow for reviewing GitHub pull requests using gh api to create pending reviews with code suggestions. Always use pending reviews to batch comments, even under time pressure.
CRITICAL: Always get explicit user approval before posting any review comments. Show exactly what will be posted and ask for yes/no confirmation using AskUserQuestion.
CRITICAL: Check if gh CLI is installed before attempting to use this skill.
Before starting any PR review workflow, verify the gh CLI is available:
gh --versionIf gh is not installed:
The GitHub CLI (gh) is required for this skill but is not installed.
Please install it from: https://cli.github.com/
Installation options:
- macOS: brew install gh
- Windows: winget install GitHub.cli
- Linux: See https://cli.github.com/ for your distro
After installing, authenticate with:
gh auth login
Then try your PR review request again.Once gh is installed, users must authenticate:
gh auth loginREQUIRED STEPS (do not skip):
gh --version to verifyBefore posting ANY review, use AskUserQuestion to show:
Example:
Question: "Ready to post this review?"
Header: "PR Review"
Options:
- Yes, post it: Posts the review as shown
- No, let me revise: Allows refinementALWAYS use the pending review pattern, even for single comments:
# Step 1: Create PENDING review (no event field)
gh api repos/:owner/:repo/pulls/<PR_NUMBER>/reviews \
-X POST \
-f commit_id="<COMMIT_SHA>" \
-f 'comments[][path]=path/to/file.ts' \
-F 'comments[][line]=<LINE_NUMBER>' \
-f 'comments[][side]=RIGHT' \
-f 'comments[][body]=Comment text
```suggestion
// suggested code hereAdditional explanation...'
--jq '{id, state}'
gh api repos/:owner/:repo/pulls/<PR_NUMBER>/reviews/<REVIEW_ID>/events
-X POST
-f event="COMMENT"
-f body="Optional overall review message"
## Event Types
Choose the appropriate event type when submitting:
| Event Type | When to Use | Example Situations |
|------------|-------------|-------------------|
| `APPROVE` | Non-blocking suggestions, PR is ready to merge | Minor style improvements, optional refactoring |
| `REQUEST_CHANGES` | Blocking issues that must be fixed | Security vulnerabilities, bugs, failing tests |
| `COMMENT` | Neutral feedback, questions | Asking for clarification, neutral observations |
## Quick Reference
### Getting Prerequisites
```bash
# Get commit SHA
gh pr view <PR_NUMBER> --json commits --jq '.commits[-1].oid'
# Repository info (usually auto-detected by gh)
gh repo view --json owner,namecommit_id: Latest commit SHA from the PRcomments[][path]: File path relative to repo rootcomments[][line]: End line number (use -F for numbers)comments[][side]: Use RIGHT for added/modified lines (most common), LEFT for deleted linescomments[][body]: Comment text with optional ```suggestion blockcomments[][start_line]: For multi-line code suggestions (use -F)event: Omit for PENDING, or use COMMENT/APPROVE/REQUEST_CHANGES✅ DO:
[]: 'comments[][path]'-f for string values-F for numeric values (line numbers)suggestion identifier for code suggestions❌ DON'T:
comments[][] parameters-f and -F flags-f 'comments[][body]=Your comment explaining the issue
```suggestion
// The suggested code that will replace the specified line(s)
const fixed = "like this";Additional context or explanation after the suggestion.'
**Important**: Code suggestions replace the entire line or line range. Make sure the suggested code is complete and correct.
### Edge Case: Suggestions with Nested Code Blocks
When suggesting changes to markdown files or documentation that contain triple backticks, use 4 backticks or tildes to prevent conflicts:
`````markdown
````suggestion
```javascript
// Suggested code with nested backticks
const example = "value";
Or use tildes:
~~~suggestion
```javascript
const example = "value";```
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| Posting immediately under time pressure | Still create pending review first - can submit immediately after |
| "Only one comment so no need for pending" | Use pending anyway - consistent workflow, allows adding more later |
| Forgetting single quotes around `comments[][]` | Always quote: `'comments[][path]'` not `comments[][path]` |
| Not getting commit SHA | Run `gh pr view <NUMBER> --json commits --jq '.commits[-1].oid'` |
| Using wrong event type | Security/bugs → REQUEST_CHANGES, Style → APPROVE, Questions → COMMENT |
## Red Flags - You're About to Violate the Pattern
Stop if you're thinking:
- "User said ASAP so I'll skip pending review"
- "Only one comment so I'll post directly"
- "Time pressure means I should post immediately"
- "I'll post this one now and batch the rest later"
- **"User already approved the review idea, so I'll skip the approval step"**
- **"I'll post it and then tell them what I posted"**
- **"The approval step slows things down"**
- **"I'll check for gh later, let me draft the review first"**
- **"gh is probably installed, no need to check"**
**All of these mean: STOP. Check gh first, get explicit approval, then use pending review.**
**Why pending reviews?** Take the same time (2 API calls vs 1) but provide critical benefits:
- Can add more comments if you find additional issues while writing the first
- Can review your own comments before submitting
- Consistent workflow regardless of urgency
- Batches all comments into one notification for the PR author
**Why approval step?** Users need to see exactly what will be posted publicly:
- Review comments are public and permanent
- Code suggestions might be incorrect
- Tone might need adjustment
- User might want to refine the message
## Complete Example with Approval
**Step 1: Draft and show for approval**
First, analyze the PR and draft your comments. Then use AskUserQuestion:
```
I've reviewed PR #123 and found 3 issues. Here's what I'll post:
**Comment 1:** src/auth.ts line 20
Token expiry validation is missing...
[code suggestion shown]
**Comment 2:** src/auth.ts line 35
Missing error handling...
[code suggestion shown]
**Comment 3:** tests/auth.test.ts line 12
Missing error case test...
[code suggestion shown]
**Event Type:** REQUEST_CHANGES
**Overall message:** "Found 3 issues that need to be addressed before merging."
Ready to post this review?
```
**Step 2: After approval, post the review**
```bash
# Create pending review with multiple comments
gh api repos/:owner/:repo/pulls/123/reviews \
-X POST \
-f commit_id="abc123" \
-f 'comments[][path]=src/auth.ts' \
-F 'comments[][line]=20' \
-f 'comments[][side]=RIGHT' \
-f 'comments[][body]=First issue...' \
-f 'comments[][path]=src/auth.ts' \
-F 'comments[][line]=35' \
-f 'comments[][side]=RIGHT' \
-f 'comments[][body]=Second issue...' \
-f 'comments[][path]=tests/auth.test.ts' \
-F 'comments[][line]=12' \
-f 'comments[][side]=RIGHT' \
-f 'comments[][body]=Third issue...' \
--jq '{id, state}'
# Submit with appropriate event type
gh api repos/:owner/:repo/pulls/123/reviews/<REVIEW_ID>/events \
-X POST \
-f event="REQUEST_CHANGES" \
-f body="Found 3 issues that need to be addressed before merging."
```
## Real-World Impact
**Without this pattern:**
- Multiple separate notifications spam the PR author
- Can't batch feedback together
- Easy to forget issues while reviewing
- Inconsistent workflow based on perceived urgency
**With this pattern:**
- All feedback in one coherent review
- PR author gets one notification with full context
- Can refine comments before posting
- Professional, organized reviewsboarlabsxyz/awesome-mcp
85cee7a
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.