Github Pr Review

GitHub PR Review

Post structured code review feedback using the GitHub API with inline comments on specific lines.

Key Rule: One API Call

Bundle ALL comments into a single review API call. Do not post comments individually.

Posting a Review

Use the GitHub CLI (gh) with a JSON input file. The GITHUB_TOKEN is automatically available.

Important: Always use --input with a JSON file instead of -F flags. This avoids shell quoting issues with special characters in comment bodies (quotes, backticks, newlines, etc.) and eliminates the need for complex heredoc scripts.

Step 1: Create a JSON file

cat > /tmp/review.json << 'EOF'
{
  "commit_id": "{commit_sha}",
  "event": "COMMENT",
  "body": "Brief 1-3 sentence summary.",
  "comments": [
    {
      "path": "path/to/file.py",
      "line": 42,
      "side": "RIGHT",
      "body": "🟠 Important: Your comment here."
    },
    {
      "path": "another/file.js",
      "line": 15,
      "side": "RIGHT",
      "body": "🟡 Suggestion: Another comment."
    }
  ]
}
EOF

Step 2: Post the review

gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/reviews --input /tmp/review.json

Parameters

Multi-Line Comments

For comments spanning multiple lines, add start_line to specify the range:

{
  "path": "path/to/file.py",
  "start_line": 10,
  "line": 12,
  "side": "RIGHT",
  "body": "🟡 Suggestion: Refactor this block:\n\n```suggestion\nline_one = \"new\"\nline_two = \"code\"\nline_three = \"here\"\n```"
}

Important: The suggestion must have the same number of lines as the range (e.g., lines 10-12 = 3 lines).

Priority Labels

Start each comment with a priority label. Minimize nits - leave minor style issues to linters.

Do NOT post 🟢 Nit or 🟢 Acceptable comments. If code is fine, simply don't comment on it. Inline comments that say "this looks good" or "acceptable trade-off" are noise — they create review threads that must be resolved without providing actionable value.

Example:

🟠 Important: This function doesn't handle None, which could cause an AttributeError.

if user is None: raise ValueError("User cannot be None")

GitHub Suggestions

For small code changes, use the suggestion syntax for one-click apply:

~~~

improved_code_here()

~~~

Use suggestions for: renaming, typos, small refactors (1-5 lines), type hints, docstrings.

Avoid for: large refactors, architectural changes, ambiguous improvements.

Finding Line Numbers

# From diff header: @@ -old_start,old_count +new_start,new_count @@
# Count from new_start for added/modified lines

grep -n "pattern" filename     # Find line number
head -n 42 filename | tail -1  # Verify line content

Fallback: curl

If gh is unavailable, use curl with the JSON file:

curl -X POST \
  -H "Authorization: token $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/{owner}/{repo}/pulls/{pr_number}/reviews" \
  -d @/tmp/review.json

Summary

1. Analyze the code and identify important issues (minimize nits) 2. Write review data to a JSON file (e.g., /tmp/review.json) 3. Post ONE review using gh api --input /tmp/review.json 4. Use priority labels (🔴🟠🟡) on every comment 5. Do NOT post comments for code that is acceptable — only comment when action is needed 6. Use suggestion syntax for concrete code changes 7. Keep the review body brief (details go in inline comments) 8. If no issues: post a short approval message with no inline comments

Read and follow the complete instructions in the SKILL.md file located in this skill's directory.

$ARGUMENTS

Github Pr Review

Post PR review comments using the GitHub API with inline comments, suggestions, and priority labels.

Triggers

This skill is activated by the following keywords:

• /github-pr-review

Details

GitHub PR Review

Post structured code review feedback using the GitHub API with inline comments on specific lines.

Key Rule: One API Call

Bundle ALL comments into a single review API call. Do not post comments individually.

Posting a Review

Use the GitHub CLI (gh). The GITHUB_TOKEN is automatically available.

gh api \
  -X POST \
  repos/{owner}/{repo}/pulls/{pr_number}/reviews \
  -f commit_id='{commit_sha}' \
  -f event='COMMENT' \
  -f body='Brief 1-3 sentence summary.' \
  -f comments[][path]='path/to/file.py' \
  -F comments[][line]=42 \
  -f comments[][side]='RIGHT' \
  -f comments[][body]='🟠 Important: Your comment here.' \
  -f comments[][path]='another/file.js' \
  -F comments[][line]=15 \
  -f comments[][side]='RIGHT' \
  -f comments[][body]='🟡 Suggestion: Another comment.'

Parameters

Multi-Line Comments

For comments spanning multiple lines, add start_line to specify the range:

  -f comments[][path]='path/to/file.py' \
  -F comments[][start_line]=10 \
  -F comments[][line]=12 \
  -f comments[][side]='RIGHT' \
  -f comments[][body]='🟡 Suggestion: Refactor this block:

line_one = "new" line_two = "code" line_three = "here" ```'

**Important**: The suggestion must have the same number of lines as the range (e.g., lines 10-12 = 3 lines).

## Priority Labels

Start each comment with a priority label:

| Label | When to Use |
|-------|-------------|
| 🔴 **Critical** | Must fix: security vulnerabilities, bugs, data loss risks |
| 🟠 **Important** | Should fix: logic errors, performance issues, missing error handling |
| 🟡 **Suggestion** | Nice to have: better naming, code organization |
| 🟢 **Nit** | Optional: formatting, minor style preferences |

**Example:**

🟠 Important: This function doesn't handle None, which could cause an AttributeError.

if user is None:
    raise ValueError("User cannot be None")

## GitHub Suggestions

For small code changes, use the suggestion syntax for one-click apply:

~~~

improved_code_here()

~~~

Use suggestions for: renaming, typos, small refactors (1-5 lines), type hints, docstrings.

Avoid for: large refactors, architectural changes, ambiguous improvements.

## Finding Line Numbers

From diff header: @@ -old_start,old_count +new_start,new_count @@

Count from new_start for added/modified lines

grep -n "pattern" filename # Find line number head -n 42 filename | tail -1 # Verify line content

## Fallback: curl

If `gh` is unavailable:

curl -X POST \ -H "Authorization: token $GITHUB_TOKEN" \ -H "Accept: application/vnd.github+json" \ "https://api.github.com/repos/{owner}/{repo}/pulls/{pr_number}/reviews" \ -d '{ "commit_id": "{commit_sha}", "event": "COMMENT", "body": "Review summary.", "comments": [ {"path": "file.py", "line": 42, "side": "RIGHT", "body": "Comment"}, {"path": "file.py", "start_line": 10, "line": 12, "side": "RIGHT", "body": "Multi-line"} ] }'

## Summary

1. Analyze the code and identify issues
2. Post **ONE** review with all inline comments bundled
3. Use priority labels (🔴🟠🟡🟢) on every comment
4. Use suggestion syntax for concrete code changes
5. Keep the review body brief (details go in inline comments)
6. If no issues: post a short approval message