AI Code Review Skill | Agent Skills

AI Code Review

Perform a structured code review of the current branch's changes and post results to GitLab (in CI) or display them locally.

Step 1: Review Code Changes

Review ALL commits in the branch since the base branch. The git workspace is already checked out with the branch to review. Use git commands to inspect the changes — do NOT access remote APIs (e.g., glab commands).

git log --oneline origin/main..HEAD
git diff origin/main..HEAD

Adjust the base branch name if different from main (e.g., master, develop). In CI, $CI_MERGE_REQUEST_DIFF_BASE_SHA identifies the exact base commit.

Only review the committed diff between branches. Do NOT run git status, do NOT report on untracked files, and do NOT include uncommitted working-tree changes in your review.

Review Guidelines

$ARGUMENTS

If no additional instructions were provided above, follow these defaults:

Provide constructive feedback that helps maintain code quality and follows project best practices. Be selective and focused: only comment on issues that genuinely matter. Do not comment for the sake of commenting. If the code is well-written and follows best practices, it is perfectly acceptable to return zero inline comments. Prioritize critical and major issues over minor stylistic preferences. Avoid repeating the same type of feedback across multiple locations — one representative comment is sufficient.

When referencing coding standards, security norms, best practices, or component-specific behavior, search for and cite the authoritative source (official documentation, RFCs, upstream references) to back up the claim.

Step 2: Produce Review JSON

Write your review output as a JSON file at /tmp/ai-review-output.json.

The JSON must be a valid object matching this schema exactly:

{
  "summary": "Brief overall assessment of the changes (2-4 sentences, markdown allowed inside this string)",
  "positive_aspects": ["List of good practices and well-implemented features"],
  "inline_comments": [
    {
      "file": "path/to/file (relative to repo root)",
      "line": 42,
      "severity": "critical|major|minor|suggestion",
      "comment": "Description of the issue and suggested fix (markdown allowed inside this string)"
    }
  ],
  "fix_prompt": "Optional: a copy-paste prompt to fix all issues found. Omit this field if there are no actionable fixes."
}

Inline comments rules

ONLY comment on lines that appear in the diff (changed or added lines). Do NOT comment on unchanged lines.
Use the line number as it appears in the NEW version of the file.
file must be the path relative to the repository root (e.g., src/main.py, not /workspace/src/main.py).
Severity levels:
- critical: Security vulnerabilities, build-breaking changes
- major: Significant logic errors, pattern violations
- minor: Style issues, minor improvements
- suggestion: Optional improvements for code quality
Each comment should be self-contained and actionable.
If there are no inline issues to report, use an empty array [].

Summary rules

Keep it short (2-4 sentences). The inline comments carry the detail.
Mention the overall quality and any critical concerns.

Positive aspects rules

List 1-3 things done well. If nothing stands out, use an empty array [].

Fix prompt rules

Omit this field entirely if there are no actionable fixes.

Step 3: Post Results

Run the review.py script from this skill's scripts/ directory. Execute it directly (not via python) to invoke uv via the shebang:

./scripts/review.py post /tmp/ai-review-output.json

The script auto-detects the platform (GitLab CI, GitHub, or local) and handles:

JSON validation and chill-mode filtering (controlled by $CHILL_MODE env var)
Deduplication against previous reviews (skips comments on unchanged code)
Deleting previous AI review discussions on the MR (GitLab)
Posting inline comments and a summary note to the MR (GitLab)
Falling back to formatted terminal display when no CI platform is detected

If the script reports a JSON parse error, fix the JSON in /tmp/ai-review-output.json and re-run the command.

Step 4: Report Results

After the script completes successfully:

CI: Confirm the review was posted to the merge request
Local: The script displays results directly in the terminal
Errors: Report any failures from the script output

Gotchas

Line numbers in inline_comments must reference the NEW file version, not the old one; using old-side line numbers causes comments to land on the wrong line in GitLab.
The JSON output must be strict JSON (no trailing commas, no comments). Invalid JSON will cause the posting script to fail.
Running git status or reviewing uncommitted changes will produce false findings that are not part of the MR diff.

Environment Variables

The Python script reads these from the environment. In GitLab CI, most are set automatically — no manual configuration needed.

GitLab

| Variable | Required for | Default | Description | |----------|-------------|---------|-------------| | GITLAB_API_TOKEN | CI/MR | — | GitLab Personal Access Token | | CI_SERVER_URL | — | https://gitlab.com | GitLab server URL | | CI_PROJECT_ID | CI/MR | — | GitLab project ID | | CI_MERGE_REQUEST_IID | CI/MR | — | Merge request IID | | CI_MERGE_REQUEST_DIFF_BASE_SHA | CI/MR | — | Base SHA for diff positioning | | CI_COMMIT_SHA | CI/MR | — | Head commit SHA | | CI_JOB_NAME | — | ai-review | Job name for summary footer | | CI_JOB_URL | — | # | Job URL for summary footer |

Common

| Variable | Required for | Default | Description | |----------|-------------|---------|-------------| | CHILL_MODE | — | true | Filter out suggestion-level comments | | VERBOSE | — | false | Show detailed API error responses |

Agent Skills: AI Code Review

Install this agent skill to your local

Skill Files