code-review-skill

Two portable Code Review Agent Skills that share one review standard —
one for local changes before they become a PR, one for existing GitHub
Pull Requests.

Each Skill is packaged around a canonical
Agent Skills SKILL.md and runs on
any Agent Skills-compatible runtime (Claude Code, Codex, Cursor, OpenCode,
…). Optional runtime adapters may improve discovery but never change review
behavior.

Licensed under the Apache License 2.0.

Explanatory, navigational documentation — onboarding, a Skill-selection
guide, and a dated AI code-review landscape comparison — lives in the
GitHub Wiki. It
never overrides the canonical files in this repository.

What this repository provides

Both are read-only for your code: neither edits files, commits, pushes,
or merges. github-pr-review's strongest positive action is Approve.

Which Skill should I use?

Rule of thumb: no PR yet → local-code-review; a PR exists and you are
not its author → github-pr-review. An implementing Agent never reviews
its own PR — see
policies/review-orchestration-policy.md,
"Implementation Workflow Termination and Reviewer/Author Separation." Full
side-by-side detail is
in docs/CODE_REVIEW_COMPARISON.md §9.

Install / package

Building a Skill produces one standalone archive with SKILL.md and
LICENSE at its root (never nested under a skills/ path), so a consumer
never needs to know this repository's layout. Pick the archive that matches
how the reviewer will be used — packaging both is rarely needed.

Quick start

1. Package the Skill you need (above).
2. Install the archive into your runtime's Skill directory — for
   example .claude/skills/<name>/, .agents/skills/<name>/,
   .cursor/skills/<name>/, or .opencode/skills/<name>/. Each archive
   already keeps SKILL.md at its own root, so unzip it directly into that
   directory.
3. Invoke it from the runtime.

   • local-code-review is opt-in — it runs only when you explicitly ask,
     every time. Optionally pass review context to focus attention:

     /local-code-review
     
     Context source: Jira PROJECT-1234
     Acceptance criteria:
     - reject writes to a record while it is locked
     - validation must occur before the write is persisted
     

     A bare /local-code-review with no context is fully supported.

   • github-pr-review takes a PR URL or number.

Missing optional context never fails or degrades a review.

Capabilities and guarantees

Both Skills apply one portable review governance protocol on top of
ordinary bug-finding — the durable value is how a review is controlled,
not only what it finds:

• Read-only — no edits, commits, pushes, merges, or branch management.
• Opt-in local review — local-code-review needs fresh, explicit user
  approval for every invocation, including each re-review after a fix.
• Self-review is allowed; self-approval is not — github-pr-review
  analyzes its own PR and produces a real verdict, but never submits a
  formal APPROVE / REQUEST_CHANGES on the reviewer's own work.
• Analysis is separate from GitHub mutation authority — one canonical
  publication mode (PASSIVE / SEMI / ACTIVE), defaulting to
  non-mutating PASSIVE; an explicit ACTIVE request is itself
  sufficient authorization to publish, subject to genuine reviewer
  independence and GitHub permission.
• One reviewer owner per scope, exact reviewed-HEAD tracking, and
  HEAD revalidation before the decision, so a changed HEAD is never
  approved as the SHA that was actually reviewed.
• Shared P0/P1/P2 severity model with a mechanical blocking rule,
  identical in both Skills.

Optional and advanced capabilities — review context, runtime
validation evidence, parallel review, human-style output, delta / SHA-aware
re-review, GitHub publication & review authorization, and the coding-agent
fix prompt — each has a short usage guide, with which Skill supports it
and how it is activated, in the capability catalog
docs/features/.

Not implemented: any GitHub-side merge or auto-merge,
branch-protection changes beyond one opt-in required-check setup, and any
execution of the target repository's code. See
docs/CODE_REVIEW_COMPARISON.md §3 and §10.

Requirements

• Git — required for both Skills.
• Authenticated GitHub access — required for github-pr-review to read
  PR state; sufficient review permissions are required only to
  publish an active review. A complete review can still report findings
  when GitHub does not permit that account to submit Approve or Request
  Changes. Credentials come from the environment and are never stored in
  either Skill.
• Python 3 — only to run this repository's validation, packaging, and
  test tooling (see below). It is not a runtime dependency of either
  packaged Skill.

Contributing to this repository

Contributions are welcome. Issues labeled help wanted or good first issue
are available for anyone to claim without prior approval. See
CONTRIBUTING.md for the fork, /claim, pull request,
review, and merge workflow.

Development of this repository follows its own canonical rules in
AGENTS.md and the focused policies/ it
routes to — a dedicated branch per task, squash-merge by default,
read-only Git safety, and the documentation-UX standards in
policies/documentation-policy.md.
Opening a PR here applies
.github/PULL_REQUEST_TEMPLATE.md
automatically — its compact What / Validation / Review shape keeps Issue,
contract, governance, packaging, changelog, and review traceability scannable.

Validation and packaging run from the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
python3 scripts/validation/validate-skill-metadata.py skills/local-code-review --containment-root .
python3 scripts/validation/validate-skill-metadata.py skills/github-pr-review --containment-root .
python3 scripts/validation/validate-markdown-links.py
python3 -m unittest discover -s tests -t .
./scripts/packaging/package-skills.sh all

On Windows PowerShell, activate with .venv\Scripts\Activate.ps1, use
python in place of python3, and package with
./scripts/packaging/package-skills.ps1 all. Packaging also needs the zip and
unzip command-line tools on macOS/Linux, or PowerShell on Windows. Generated
archives stay under the ignored dist/ directory.

Run one test module with, e.g.,
python3 -m unittest tests.unit.test_reviewer_ownership.

Packaging internals — how the source layout under skills/<name>/ and
shared/ becomes the flat archive layout, and how package-relative links
are rewritten during staging — are described in
docs/ARCHITECTURE.md §7.

Deeper documentation