Tohuhono/Oberon / .agents/skills/github-pr-review
github-pr-review
VerifiedUse 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)
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
SKILL.md
View on GitHub---
name: github-pr-review
description:
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)
---
# GitHub PR Review
## Overview
Workflow 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.**
## When to Use
- Reviewing pull requests
- Adding code suggestions to PRs
- Posting review comments with the gh CLI
## Core Workflow
**REQUIRED STEPS (do not skip):**
1. **Draft the review** - Analyze PR and prepare all comments
2. **Post the review**
### Technical Workflow
````bash
# 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 here
````
Additional explanation...' \
--jq '{id, state}'
# Returns: {"id": <REVIEW_ID>, "state": "PENDING"}
# Step 2: Submit the pending review
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,name
````
### Required Parameters
- `commit_id`: Latest commit SHA from the PR
- `comments[][path]`: File path relative to repo root
- `comments[][line]`: End line number (use `-F` for numbers)
- `comments[][side]`: Use `RIGHT` for added/modified lines (most common), `LEFT` for deleted lines
- `comments[][body]`: Comment text with optional ```suggestion block
### Optional Parameters
- `comments[][start_line]`: For multi-line code suggestions (use `-F`)
- `event`: Omit for PENDING, or use `COMMENT`/`APPROVE`/`REQUEST_CHANGES`
### Syntax Rules
✅ **DO:**
- Use single quotes around parameters with `[]`: `'comments[][path]'`
- Use `-f` for string values
- Use `-F` for numeric values (line numbers)
- Use triple backticks with `suggestion` identifier for code suggestions
❌ **DON'T:**
- Use double quotes around `comments[][]` parameters
- Mix up `-f` and `-F` flags
- Forget to get commit SHA first
## Code Suggestions Format
````bash
-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:
`````markdown
````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"
**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
**Example**
```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 reviews
```
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |