GitHub Review Skill

Automated code review skill for pull requests. Collects PR context, performs AI-powered code review, and publishes structured reviews with inline comments.

Environment and Paths

This skill uses environment variables to stay portable across Holon, local shells, and CI.

Key Environment Variables

•
GITHUB_OUTPUT_DIR: Output directory for artifacts and review results
- •Default: /holon/output when the path exists (Holon container); otherwise a temp dir under /tmp/holon-ghreview-*
- •Custom: Set to any directory (e.g., ./output, /tmp/github-work)
•
GITHUB_CONTEXT_DIR: Directory for collected GitHub context
- •Default: ${GITHUB_OUTPUT_DIR}/github-review-context
- •Custom: Set to override the context directory
•
GITHUB_TOKEN / GH_TOKEN: GitHub authentication token
- •Required for both collection and publishing
- •Must have pull:read and pull:write scopes
•
MAX_INLINE: Maximum inline comments to post (default: 20)
- •Limits the number of inline comments to avoid overwhelming reviewers
•
POST_EMPTY: Post review even when no findings (default: false)
- •When false, skill exits silently if no issues are found
- •When true, posts a "no issues found" review comment
•
MAX_FILES: Maximum number of files to collect from the pull request
- •When unset, the collection script's internal default (100) is used
•
INCLUDE_THREADS: Whether to include review comment threads and discussions in collected context
- •Set to true to include discussion threads; when unset, the collection script's default behavior applies

Path Examples

bash

# Holon container (default picked up automatically)
export GITHUB_OUTPUT_DIR=/holon/output

# Local development (keeps workspace clean by defaulting to /tmp if unset)
export GITHUB_OUTPUT_DIR=./output
export GITHUB_TOKEN=ghp_xxx

# CI/CD environment
export GITHUB_OUTPUT_DIR=${PWD}/artifacts
export GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}
export MAX_INLINE=10

Workflow

This skill follows a three-step workflow:

1. Collect Context

Run scripts/collect.sh <PR_REF> to gather PR information:

•PR metadata (title, description, author, stats)
•Changed files list with full diff
•Existing review threads (to avoid duplicates)
•PR comments and commit history

2. Perform Review

Agent analyzes the collected context and generates:

•review.md - Human-readable review summary
•review.json - Structured findings with path/line/severity/message
•summary.md - Brief process summary

Agent follows review guidelines in prompts/review.md.

3. Publish Review

Run scripts/publish.sh to post the review:

•Creates or updates a PR review via GitHub API
•Posts inline comments for findings with path+line information
•Limits inline comments via MAX_INLINE (default: 20)

Usage

Basic Usage

bash

# Review a PR
holon --skill github-review holon-run/holon#123

# Review using full URL
holon --skill github-review https://github.com/holon-run/holon/pull/123

With Collection Script

bash

# Step 1: Collect PR context
export GITHUB_OUTPUT_DIR=/holon/output
/holon/workspace/skills/github-review/scripts/collect.sh "holon-run/holon#123"

# Step 2: Agent performs review and generates artifacts
# (Agent reads context from ${GITHUB_OUTPUT_DIR}/github-review-context/)
# (Agent writes review.md and review.json to ${GITHUB_OUTPUT_DIR}/)

# Step 3: Publish review
/holon/workspace/skills/github-review/scripts/publish.sh

Advanced Options

bash

# Preview review without posting (dry-run)
export DRY_RUN=true
holon --skill github-review holon-run/holon#123

# Limit inline comments
export MAX_INLINE=10
holon --skill github-review holon-run/holon#123

# Post review even if no findings
export POST_EMPTY=true
holon --skill github-review holon-run/holon#123

# Combine options
export MAX_INLINE=15 POST_EMPTY=true
holon --skill github-review holon-run/holon#123

Scripts

This skill includes executable scripts in scripts/:

•collect.sh: Collects PR context (metadata, diff, comments, etc.)
•publish.sh: Publishes reviews with inline comments via GitHub API

For detailed script documentation, usage, and examples, see references/SCRIPTS.md.

Agent Prompts

prompts/review.md: Review guidelines and output format for agents

Agents should read this file to understand review priorities, what to skip, and how to structure findings.

Output Contract

Required Inputs (from collection script)

•${GITHUB_CONTEXT_DIR}/github/pr.json: PR metadata
•${GITHUB_CONTEXT_DIR}/github/files.json: Changed files list
•${GITHUB_CONTEXT_DIR}/github/pr.diff: Full diff of changes

Optional Inputs (from collection script)

•${GITHUB_CONTEXT_DIR}/github/review_threads.json: Existing review comments
•${GITHUB_CONTEXT_DIR}/github/comments.json: PR discussion comments
•${GITHUB_CONTEXT_DIR}/github/commits.json: Commit history

Required Outputs (from agent)

•
${GITHUB_OUTPUT_DIR}/review.md: Human-readable review summary
- •Overall summary of the PR
- •Key findings by severity
- •Detailed feedback organized by category
- •Positive notes and recommendations

•

${GITHUB_OUTPUT_DIR}/review.json: Structured review findings

json

[
  {
    "path": "path/to/file.go",
    "line": 42,
    "severity": "error|warn|nit",
    "message": "Clear description of the issue",
    "suggestion": "Specific suggestion for fixing (optional)"
  }
]

•
${GITHUB_OUTPUT_DIR}/summary.md: Brief summary of the review process
- •PR reference and metadata
- •Number of findings
- •Review outcomes

Optional Outputs (from agent)

•${GITHUB_OUTPUT_DIR}/manifest.json: Execution metadata

json

{
  "provider": "github-review",
  "pr_ref": "holon-run/holon#123",
  "findings_count": 5,
  "inline_comments_count": 3,
  "status": "completed|completed_with_empty|failed"
}

Context Files

When context is collected, the following files are available under ${GITHUB_CONTEXT_DIR}/github/:

•pr.json: Pull request metadata
•files.json: List of changed files
•pr.diff: Full diff of changes
•review_threads.json: Existing review comments (if any)
•comments.json: PR discussion comments (if any)
•commits.json: Commit history (if any)

Workflow

Complete Review Workflow

•
Collection (collect.sh)
- •Fetch PR context using gh CLI
- •Write to ${GITHUB_CONTEXT_DIR}/github/
- •Generate manifest.json
•
Review (agent)
- •Read PR context from ${GITHUB_CONTEXT_DIR}/github/
- •Analyze changes according to prompts/review.md guidelines
- •Generate review.md and review.json
- •Write to ${GITHUB_OUTPUT_DIR}/
•
Publishing (publish.sh)
- •Read agent artifacts from ${GITHUB_OUTPUT_DIR}/
- •Post structured review to GitHub API
- •Inline comments for findings with path+line
- •Summary from review.md

Integration Examples

Holon Skill Mode

yaml

# .github/workflows/pr-review.yml
name: PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Holon review
        uses: holon-run/holon@main
        with:
          skill: github-review
          args: ${{ github.repository }}#${{ github.event.pull_request.number }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          MAX_INLINE: 20

Manual Review

bash

# Review a PR manually
export GITHUB_TOKEN=ghp_xxx
export GITHUB_OUTPUT_DIR=./my-review
mkdir -p $GITHUB_OUTPUT_DIR

# Collect context
/holon/workspace/skills/github-review/scripts/collect.sh "holon-run/holon#123"

# Perform review (agent reads context, generates findings)
# ... agent processes ...

# Preview review
/holon/workspace/skills/github-review/scripts/publish.sh --dry-run

# Publish review
/holon/workspace/skills/github-review/scripts/publish.sh

Important Notes

•Idempotency: The skill fetches existing review threads to avoid duplicating comments
•Rate limits: GitHub API has rate limits; the skill uses pagination and batching appropriately
•Large PRs: Use MAX_FILES to limit context collection for PRs with many changed files
•Inline limits: Use MAX_INLINE to avoid overwhelming reviewers with too many comments
•Silent success: By default, the skill doesn't post reviews when no findings are found (use POST_EMPTY=true to change this)
•Headless operation: The skill runs without user interaction; all configuration is via environment variables

Capabilities

You MAY use these commands directly via gh CLI:

•gh pr view - View PR details
•gh pr diff - Get PR diff
•gh api - Make API calls

You MUST NOT use these directly (use artifacts instead):

•gh pr review - Use scripts/publish.sh instead

Reference Documentation

See prompts/review.md for detailed review guidelines and instructions.