a-review-skill/README.md

a-review-skill

A Claude Code skill that runs an independent AI code review after a coding session. The reviewer is a different model from the one that wrote the code — Gemini CLI, a local Ollama, or any text-in/text-out backend — and runs read-only so it can produce findings but never edits files.

This complements zero-check rather than replacing it:

• zero-check = deterministic gauntlet (lint, SAST, deps, tests).
• a-review = subjective second opinion ("did you miss something a linter wouldn't catch?").

Run zero-check first, a-review after.

How it works

1. Assembles a context packet from the project: CLAUDE.md (so the reviewer knows the architecture + conventions), the latest session notes (so the reviewer knows the intent), git diff -U10 HEAD~1 (the change in surrounding context), and git diff --stat HEAD~1 (scope summary).
2. Pipes the packet plus the prompt template at a-review/references/review-prompt.md to whichever backend is configured.
3. Saves the reviewer's output to reviews/a-review-YYYY-MM-DD.md in the project, with a header noting the model + diff scope.
4. Surfaces the findings to you — grouped by severity if the reviewer used severity labels, with anything critical or security-related highlighted.

Install

The skill is packaged as a-review.skill (a zip of SKILL.md, references/, and scripts/). Two install paths:

From the packaged .skill (preferred for sharing):

# Drop the file into your Claude Code skills dir
cp a-review.skill ~/.claude/skills/

From the source tree (for development):

# Symlink (or copy) the unpacked dir
ln -s "$(pwd)/a-review" ~/.claude/skills/a-review

After install, the skill triggers on:

• /a-review slash command
• Phrases like "review my changes", "get a second opinion", "run a-review", or "check this with gemini/ollama"
• Automatically after a coding session with substantive changes (per the skill description)

Backends

Backend	How it's invoked	Notes
Gemini CLI (default)	gemini -p "$(cat references/review-prompt.md)" --approval-mode plan	--approval-mode plan is required — keeps the reviewer read-only.
Ollama	HTTP POST /api/generate against http://localhost:11434	Pick a code-tuned local model (codellama, deepseek-coder, etc.).
Anything else	Pipe the assembled context + prompt to its CLI / API	The skill is text-in / text-out; no backend-specific code needed.

The skill checks for .a-review.yml in the project root and uses the configured backend if present, otherwise defaults to Gemini CLI.

Manual usage

You can run the same pipeline by hand:

# From any git project root
python /path/to/a-review-skill/a-review/scripts/assemble_context.py | \
  GEMINI_CLI_TRUST_WORKSPACE=true \
  gemini -p "$(cat /path/to/a-review-skill/a-review/references/review-prompt.md)" \
  --approval-mode plan

Useful for debugging the context packet or trying an ad-hoc model.

Repo layout

a-review-skill/
  a-review/
    SKILL.md                   # Skill definition (triggers + workflow)
    references/
      review-prompt.md         # Prompt sent to the reviewer
    scripts/
      assemble_context.py      # Builds the context packet
  a-review.skill               # Packaged zip (SKILL.md + references/ + scripts/)
  sessions/                    # Per-project session notes (skill self-dogfoods)
  CLAUDE.md                    # Agent notes
  README.md                    # This file

Packaging a new release

cd a-review && zip -r ../a-review.skill SKILL.md references/ scripts/