Git Review Skill — AI code review for GitHub PRs and Git commits

git-review-skill is an open-source Agent Skill for reviewing GitHub pull requests, Git commits, and commit ranges with Codex, Claude Code, Cursor, or Gemini CLI. It checks the exact revision, traces changed behavior across files, reads relevant code comments and earlier PR reviews, and reports actionable defects and material risks with precise locations. After a PR report, it offers to post a GitHub review comment and, for an APPROVE verdict, to merge the PR. Each action needs the user's explicit choice.

Start here: Install the skill · See the report format · Run the evaluation cases

Maintainers can use the GitHub launch and discoverability guide for repository metadata, relevant topics, and an evidence-based release checklist.

The central rule is simple: a finding needs a reproducible trigger, a concrete consequence, and a location in a pinned revision. The package pairs that rule with a deterministic scope helper and runnable cases that measure both missed defects and false positives.

The skill is language agnostic and follows the open Agent Skills specification. It uses ordinary Git access; GitHub CLI is helpful for PR metadata and private PRs but is not required for local commits. The optional Python helper inventories local change scope. The project adds no service, telemetry, or model-specific prompt syntax; private PR access uses the host agent's existing GitHub credentials.

What it does

• Pins the review target. A PR, a single commit, an explicit range, and a merge commit have different comparison rules. The skill records base/head SHAs and does not silently review a dirty working tree.
• Looks beyond the patch. It traces callers, contracts, state changes, configuration, migrations, and tests when needed.
• Reads the surrounding conversation. It checks code comments and docstrings for documented intent, then verifies those claims in code. For PRs, it reconciles earlier reviews and discussion with the current head so fixed issues are not repeated.
• Balances risk categories. Correctness, security, data integrity, compatibility, concurrency, performance, failure handling, and targeted test gaps receive attention where relevant.
• Disciplines findings. A candidate must have a reachable trigger and consequence; the reviewer checks whether it predates the change and tries to falsify it before reporting.
• Keeps noise low. Style nits, generic test requests, speculative edge cases, and performance claims without a realistic workload stay out of the findings.
• Treats reviewed content as data. Instructions inside PR descriptions, commit messages, or code comments do not control the reviewer.
• Offers controlled follow-up. A PR report ends with a choice to post one GitHub review comment. An APPROVE verdict also offers a separate merge choice; the agent rechecks the reviewed head and GitHub requirements before acting.

This is a review workflow, not a guarantee that a change has no bugs. A short smoke evaluation suite is included so maintainers can test detection and false positives without claiming an unsupported benchmark score.

Install

Install from https://github.com/salarkb/git-review-skill using the commands below. The repository includes Codex and Claude Code marketplaces, a Cursor plugin marketplace, and a Gemini CLI extension. Each packages the same skills/git-review workflow.

Codex: install from the marketplace

Run these commands in a terminal:

codex plugin marketplace add salarkb/git-review-skill
codex plugin add git-review@git-review-skill

Start a new Codex session after installation. You can also open /plugins in Codex CLI or the Plugins Directory in the desktop app and install git-review from the added marketplace. The official OpenAI plugin guide documents repository marketplaces and the Codex commands reference documents these CLI commands.

Claude Code: install from the marketplace

Run these commands inside a local Claude Code session:

/plugin marketplace add salarkb/git-review-skill
/plugin install git-review@git-review-skill

The second command opens the plugin details, where you choose the install scope. After installation, invoke /git-review:git-review or ask Claude to use the skill. The Claude Code marketplace guide documents this flow. Claude Code browser cloud sessions do not load plugins installed on your machine; see Claude's cloud-session limits.

Gemini CLI: install from the repository

Run this in a terminal, then start or restart Gemini CLI:

gemini extensions install https://github.com/salarkb/git-review-skill

Check discovery with /skills list in Gemini CLI. The root gemini-extension.json and skills/ directory follow the Gemini extension format.

Cursor: install as a plugin

After publishing, import the GitHub repository from Customize → Plugins → From GitHub Repository, then install git-review from that marketplace. The repository contains .cursor-plugin/marketplace.json and a plugin manifest. Public Cursor Marketplace listing is a separate submission and review process.

Direct skill copy

Copy the entire skills/git-review folder, including SKILL.md, references/, and scripts/, to the appropriate directory:

These locations are documented by Claude Code, Cursor, Gemini CLI, and Codex. For a team, commit a project-level copy to the repository that will use it. Agent behavior and permissions still depend on the host application.

Use

Open the repository in your agent and name the exact target. Examples:

Use git-review to review commit 3a1b... in this repository. Report only actionable findings and risks.

Use git-review to review https://github.com/ORG/REPO/pull/123. Pin the current head SHA and report findings in chat.

Use git-review to review the net changes from BASE_SHA to HEAD_SHA.

With a direct Claude Code skill copy, invoke /git-review; with the marketplace plugin, invoke /git-review:git-review. Gemini CLI can list discovered skills with /skills list and reload them with /skills reload. In Codex, $git-review selects it explicitly. Cursor can select it when the request matches its description. See each host's documentation for current invocation behavior.

Optional local scope helper

The helper needs Python 3.10+ and Git. PR mode also needs GitHub CLI (gh) with access to the PR. It prints JSON; it does not check out branches, edit source files, fetch Git objects, or submit a review.

# Run from this project's root; replace ../your-repo with the repository being reviewed.
python skills/git-review/scripts/review_scope.py --repo ../your-repo commit HEAD
python skills/git-review/scripts/review_scope.py --repo ../your-repo range BASE_SHA HEAD_SHA
python skills/git-review/scripts/review_scope.py --repo ../your-repo range BASE_SHA HEAD_SHA --merge-base
python skills/git-review/scripts/review_scope.py --repo ../your-repo pr 123

The third command uses PR-style merge-base comparison. PR mode reads the current PR metadata with gh; if base and head objects exist locally, it uses Git for the diff, otherwise it points to the hosted PR diff and marks file statuses unknown. JSON includes resolved SHAs, changed files, a file-inventory completeness flag, dirty-worktree status, and the command for the full diff. The scope reference covers fallbacks and merge commits. Git's distinction between two-dot and three-dot diffs is documented in git-diff; GitHub CLI documents gh pr view and gh pr diff.

Example report

## 🔴 CRITICAL (0)
None.

## 🟠 HIGH (1)
1. Defect — Duplicate charge occurs before the idempotency check
   payments.py:2 (head 7c21...)
   Trigger: charge_once is called again with a key already present in store.
   Impact: gateway.charge runs a second time even though the old receipt is returned.
   Evidence: the new charge call precedes store.get(key); previously this path returned first.

## 🟡 MEDIUM (0)
None.

## 🟢 LOW (0)
None.

## ✅ Positive Security Controls Verified
None verified in the reviewed scope.

## Verdict: ⚠️ REQUEST CHANGES
Reason: The duplicate charge needs a fix before acceptance.
Target: Synthetic commit, head 7c21...
Checks: Code-path inspection.
Limits: No live payment gateway tested.

This example is illustrative and based on a synthetic evaluation case. Real reviews should cite the full current head revision and actual code path.

Frequently asked questions

Can it review both pull requests and individual commits?

Yes. Name a GitHub PR, a commit SHA, or a commit range. The skill uses the comparison appropriate to that target and records the reviewed SHAs. A local commit review needs Git access; a GitHub PR review also needs access to that PR.

Does it read previous PR reviews and comments in the code?

Yes, when the host agent can access them. It checks relevant code comments and docstrings against current behavior and compares earlier PR discussion with the current head. An old finding is reported again only if it still applies. If the history is inaccessible, the report states that limit.

How does it avoid noisy review comments?

Every finding must identify an introduced or newly exposed behavior, a reachable trigger, a concrete consequence, and a precise changed location. The reviewer checks callers, guards, tests, configuration, base behavior, and prior discussion before reporting. Style preferences and speculative issues do not qualify.

Will it comment on or merge the PR?

The report appears in chat first. At the end of a PR review, the agent asks whether to post it as one GitHub review comment. When the verdict is ✅ APPROVE, it separately asks whether to merge. A yes to either choice authorizes only that action on the identified PR. Before acting, the agent verifies that the reviewed head is still current. Merging also requires passing repository checks and a mergeable PR. The chat verdict does not submit a GitHub approval review; that is a separate action.

Project layout

skills/git-review/   Portable skill; copy this folder into an agent's skills directory
  SKILL.md           Core workflow and decision rules
  references/        Scope, review method, and reporting contract
  scripts/           Optional local scope helper
tests/               Cross-platform tests for the helper and fixture generator
evals/               Disposable review cases with separate answer keys
.github/workflows/   CI for helper and fixture tests
.agents/plugins/      Codex repository marketplace
plugins/git-review/    Codex plugin package with a copy of the skill
.claude-plugin/       Claude Code plugin and marketplace manifests
.cursor-plugin/       Cursor plugin and marketplace manifests
gemini-extension.json Gemini CLI extension manifest

Develop and evaluate

python -m unittest discover -s tests -v
python evals/build_cases.py --output ./temporary-review-cases

Use a new output directory for evaluation fixtures; the builder refuses to overwrite an existing path. Follow the evaluation guide to run fresh agent sessions and record results. Tests verify the deterministic tooling; they cannot prove the quality of an agent's reasoning. Contributions that improve a real missed finding or false positive are welcome; see CONTRIBUTING.md.

Limitations

The skill cannot inspect a repository or private PR the host agent cannot access. Binary or generated changes may need separate tooling. The optional helper does not fetch PR refs or submit GitHub reviews. A report should state inaccessible files, unrun checks, and stale PR heads instead of guessing.

License

MIT.