Code Review Skill

AI-powered code review that analyzes diffs and individual files for bugs, security issues, style violations, and improvement opportunities. Supports both local git diffs and GitHub pull requests.

Authentication

Set at least one LLM API key:

bash
# Option A: Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Option B: OpenAI or any OpenAI-compatible provider (Together, OpenRouter, Groq, ...)
export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.together.ai/v1"   # only when not using openai.com

# Optional: override the model (defaults: claude-sonnet-4-20250514 / gpt-4o)
export REVIEW_MODEL="moonshotai/Kimi-K2.6"

# Optional: force a specific provider when both keys are set
export REVIEW_PROVIDER="openai"   # or "anthropic"

Provider selection (auto-detected when REVIEW_PROVIDER is unset):

1. If REVIEW_PROVIDER is set, it wins.
2. Else if REVIEW_MODEL starts with claude- or anthropic/, use Anthropic.
3. Else if only one API key is set, use that provider.
4. Else (both keys, no model hint): use OpenAI.

This precedence fixes the common deployment where both ANTHROPIC_API_KEY and OPENAI_API_KEY live in .forge/secrets.enc (one is stale or for a different skill). Pre-fix the skill always preferred Anthropic and returned 401 against the stale key.

For GitHub PR review, also set:

bash
export GH_TOKEN="ghp_..."

The token needs read-only access:

| Scope (classic PAT) | Fine-grained permission | Why | |----------------------|------------------------|-----| | repo (or public_repo for public repos) | Contents: Read | Fetch PR diff and file contents |

This skill only reads diffs — it never posts comments, applies labels, or merges. For write operations, see the code-review-github skill.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ANTHROPIC_API_KEY | one-of | Anthropic API key | | OPENAI_API_KEY | one-of | OpenAI or OpenAI-compatible (Together, OpenRouter, Groq, ...) API key | | REVIEW_PROVIDER | no | Explicit provider override: anthropic or openai. When unset, auto-detected from REVIEW_MODEL prefix, then by which key is set. Prefers openai when both keys exist and no model hint disambiguates | | REVIEW_MODEL | no | Override LLM model name. Default: claude-sonnet-4-20250514 (anthropic) / gpt-5.4 (openai) | | REVIEW_MAX_DIFF_BYTES | no | Max diff size before truncation (default: 100000) | | GH_TOKEN | no | GitHub token for PR diffs — read-only access is sufficient | | FORGE_REVIEW_STANDARDS_DIR | no | Path to .forge-review/standards/ directory for custom rules | | OPENAI_BASE_URL | no | Base URL for OpenAI-compatible providers (default: https://api.openai.com/v1). Always uses /chat/completions — see OPENAI_USE_RESPONSES_API for the proprietary Responses API | | OPENAI_USE_RESPONSES_API | no | Set to 1 to use OpenAI's proprietary /responses endpoint (Codex/OAuth flow). Default off. Only relevant when OPENAI_BASE_URL points at api.openai.com |

Tool: code_review_diff

Review a code diff for bugs, security issues, and improvements. Accepts either a GitHub PR URL or a local git base ref.

Default behavior: When the user says "review my local changes" or "review changes in <path>" WITHOUT specifying a base branch, default to base_ref: "HEAD". This reviews uncommitted and untracked files — the user's work-in-progress. Do NOT ask the user for a base ref in this case. Only use main/develop as base_ref when the user explicitly says "against main" or "against develop".

Input:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | pr_url | string | no | GitHub PR URL (e.g., https://github.com/owner/repo/pull/123) | | base_ref | string | no | Git ref to compare from. Default: HEAD (uncommitted changes). Use main only if user says "against main" | | repo_path | string | no | Absolute path to the local git repository. Required when using base_ref | | focus | string | no | Review focus: bugs, security, style, all. Default: all | | extra_context | string | no | Additional context or instructions for the reviewer |

One of pr_url or base_ref is required. When using base_ref, repo_path must point to the user's local repository (scripts run in the agent's directory, not the user's project).

Output: JSON object with structured review findings.

Examples

User says → tool input mapping:

| User request | Tool input | |-------------|------------| | "Review code changes against main in ~/myproject" | {"base_ref": "main", "repo_path": "~/myproject"} | | "Review my changes since develop in /opt/app" | {"base_ref": "develop", "repo_path": "/opt/app"} | | "Review the last 3 commits in ~/myproject for security issues" | {"base_ref": "HEAD~3", "repo_path": "~/myproject", "focus": "security"} | | "Review changes on the feature/auth branch in ~/myproject" | {"base_ref": "main", "repo_path": "~/myproject"} | | "Review my local changes in ~/myproject" | {"base_ref": "HEAD", "repo_path": "~/myproject"} | | "Review my uncommitted changes in ~/myproject" | {"base_ref": "HEAD", "repo_path": "~/myproject"} | | "Review this PR https://github.com/org/repo/pull/42" | {"pr_url": "https://github.com/org/repo/pull/42"} | | "Security audit on PR 99 in org/repo" | {"pr_url": "https://github.com/org/repo/pull/99", "focus": "security"} |

Important:

• Pass repo_path exactly as the user provides it. The script handles ~ expansion internally — do NOT try to resolve ~ yourself (you do not know the user's home directory). For example, if the user says ~/myproject, pass "repo_path": "~/myproject".
• For local reviews, repo_path is required because the script runs in the agent's working directory, not the user's project directory.
• base_ref is the starting point to compare FROM. It is NOT the branch being reviewed — it is the base that changes are measured against. The diff includes both committed and uncommitted (working tree) changes relative to base_ref.
• base_ref can be a branch name (main, develop), a commit SHA, or a relative ref (HEAD~3). The script uses git merge-base to find the fork point, so only changes on the current branch are reviewed.
• When a branch has many commits (e.g., merged PRs), use HEAD~N to narrow the review scope to the most recent N commits. For example, HEAD~5 reviews only the last 5 commits.
• When the user says "review changes on branch X" or "review branch X", they mean: review the changes that branch X introduces. Use main (or the repo's default branch) as base_ref — NOT the branch name itself.
• When the user says "review my uncommitted changes" or "review my local changes", use HEAD as base_ref to show only unstaged/staged changes.

Pre-Flight Scope Check (IMPORTANT)

Before calling code_review_diff with a base_ref, the agent MUST run cli_execute to check the diff scope:

bash
cd <repo_path> && git log --oneline <base_ref>..HEAD | head -20

This shows how many commits will be reviewed. If there are more than ~5 commits:

1. Tell the user: "There are N commits between <base_ref> and HEAD. This includes: list first few commit subjects]."
2. Ask: "Would you like me to review all N commits, or narrow the scope? For example, I can review just the last 3 commits with HEAD~3."
3. Only call code_review_diff after the user confirms the scope.

This prevents reviewing unrelated changes from older commits or merged PRs on long-lived branches.

Detection Heuristics

The agent selects this tool when it detects:

• Requests mentioning "review", "diff", "PR", "pull request", "changes"
• A directory path or repository path in the user's message
• GitHub PR URLs pasted in conversation
• Requests to check code quality, find bugs, or audit changes

Response Format

json
{
  "summary": "Brief overall assessment",
  "risk_level": "low|medium|high|critical",
  "findings": [
    {
      "file": "path/to/file.go",
      "line": 42,
      "severity": "error|warning|info|nitpick",
      "category": "bug|security|style|performance|maintainability",
      "title": "Short finding title",
      "description": "Detailed explanation of the issue",
      "suggestion": "Suggested fix or improvement"
    }
  ],
  "stats": {
    "files_reviewed": 5,
    "total_findings": 3,
    "by_severity": {"error": 1, "warning": 1, "nitpick": 1}
  }
}

Tips

• Use focus: security for security-focused audits
• Use base_ref: main to review all uncommitted changes against main
• Large diffs are automatically truncated at REVIEW_MAX_DIFF_BYTES (default 100KB)
• Set FORGE_REVIEW_STANDARDS_DIR to apply org-specific coding standards

Tool: code_review_file

Deep review of a single file with full context (not just diff). Useful for thorough analysis of critical files.

Input:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | file_path | string | yes | Path to the file to review (relative to repo root, or absolute path) | | repo_path | string | no | Absolute path to the local repository. Required for local file review (scripts run in the agent's directory, not the user's project) | | pr_url | string | no | If set, fetches the file from the PR head branch | | focus | string | no | Review focus: bugs, security, style, all. Default: all | | extra_context | string | no | Additional context or instructions for the reviewer |

Output: Same JSON structure as code_review_diff.

Examples

User says → tool input mapping:

| User request | Tool input | |-------------|------------| | "Review the file src/server.go in ~/myproject" | {"file_path": "src/server.go", "repo_path": "~/myproject"} | | "Security audit on cmd/main.go in /opt/app" | {"file_path": "cmd/main.go", "repo_path": "/opt/app", "focus": "security"} | | "Review auth.py from PR #42 in org/repo" | {"file_path": "auth.py", "pr_url": "https://github.com/org/repo/pull/42"} |

Important: For local file review, repo_path is required. file_path is relative to the repo root. Resolve ~ to the absolute home directory path.

Detection Heuristics

The agent selects this tool when it detects:

• Requests to "review this file", "audit file", "check file for issues"
• A specific file path mentioned with a repository/directory path
• Single-file deep review requests (as opposed to diff-level review)

Tips

• Use this for critical files that need thorough review beyond just changes
• Combine with code_review_diff for comprehensive PR review: diff-level first, then deep-dive on flagged files
• Works with any text file: source code, configs, scripts, IaC templates

Safety Constraints

• Never executes code from the diff or reviewed files
• API keys are passed via environment variables, never logged or included in output
• Diff content is sent to the configured LLM API for analysis (respects egress_domains)
• Large diffs are truncated, not streamed, to prevent excessive API costs
• No filesystem modifications: read-only analysis only