Code Review

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:

# 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:

export GH_TOKEN="ghp_..."

The token needs read-only access:

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

Environment Variables

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 " 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:

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:

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:

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

{
  "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:

Output: Same JSON structure as code_review_diff.

Examples

User says → tool input mapping:

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