Skip to content
Back to search

code-review-skill

Auditable code review skill for Claude Code and Codex: four independent probes, evidence-backed findings, and a JSON-derived merge gate.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/kyy-logs/code-review-gate-skill with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/kyy-logs/code-review-gate-skill'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kyy-logs--code-review-skill/badge.svg)](/listings/kyy-logs--code-review-skill)

HTML

<a href="/listings/kyy-logs--code-review-skill"><img src="/api/listings/kyy-logs--code-review-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

Run this command **inside your project**:

npx -y skills add kyy-logs/code-review-skill --agent codex --skill code-review --yes

Use `--agent claude-code` for Claude Code. Codex installs to `.agents/skills/code-review/`; Claude Code installs to `.claude/skills/code-review/`. Node.js 22.20+ is required. This installs only the skill; there is no separate reviewer adapter.

Run

Ask in Claude Code:

Review these changes with code-review.

Or invoke the skill directly:

/code-review

For a fixed range:

Use code-review on commits abc123..def456

The skill supports two review modes:

- `worktree` — staged, unstaged, and untracked changes against the current `HEAD`. - `commits` — a fixed `base..head` range.

Read the result

docs/work/active/{slug}/
├── code-review.md      # human report
└── probes/
    ├── behavior-review.json
    ├── test-coverage.json
    ├── repo-guard.json
    └── impact-analysis.json

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 355 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # code-review-gate-skill
  2. English | [简体中文](README.zh-CN.md)
  3. **Evidence-backed code review. Static-first, probe-driven, and gated.**
  4. The skill sources live in [`skills/code-review-gate/`](skills/code-review-gate/) (English) and [`skills/code-review-gate-zh/`](skills/code-review-gate-zh/) (Chinese), independently of any host's installation directory. The current stable release is `v0.2.4`; see [VERSION](VERSION).
  5. [![Claude Code](https://img.shields.io/badge/Claude%20Code-skill-6B4FBB?style=flat-square)](https://claude.com/claude-code)
  6. [![Agent Skills](https://img.shields.io/badge/Agent%20Skills-standard-1f6feb?style=flat-square)](https://agentskills.io)
  7. [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
  8. [![Static-first](https://img.shields.io/badge/review-static--first-2ea44f?style=flat-square)](#what-this-is-not)
  9. [![GitHub stars](https://img.shields.io/github/stars/kyy-logs/code-review-gate-skill?style=flat-square&logo=github)](https://github.com/kyy-logs/code-review-gate-skill/stargazers)
  10. Most AI reviews stop at “this looks risky.” This skill produces a review you can audit: every finding points to a location, a contract or code path, and a severity; every gate decision is rendered from machine-readable JSON. It reads the diff, surrounding source, tests, and project rules — no build, test run, or coverage report required.
  11. It never modifies the code under review.
  12. ## Latest news
  13. <!-- NEWS:START -->
  14. ### v0.2.4 (2026-11-10)
  15. #### Changed
  16. - code-review: behavior review requires a concrete delimiter-whitespace input pair and traces match result, field/default, validation, and use
  17. - code-review: serialization review inspects the encoder/renderer/decoder and traces a quote, backslash, or newline input; unresolved decisive implementations go to `unverified_items`
  18. - code-review: when repository calls or tests establish the path, a missing external production caller is an impact-scope gap, not a blocker
  19. - code-review: probe searches prefer `git grep <head>` for commit reviews and scope caller discovery
  20. [Full update history](NEWS.md)
  21. <!-- NEWS:END -->
  22. ## Release status
  23. `v0.2.4` is a stable release within the scope described below.
  24. Pre-1.0 contract or format changes will be documented in [NEWS](NEWS.md).
  25. - **Severity is three levels:** `high`, `medium`, `low`. Records written by the
  26. earlier four-level version, including any `critical` value, are **not
  27. compatible**; `collect-metrics` rejects them. Re-run the review or migrate the
  28. records before using them with this release.
  29. - **Scope:** static-first review with four probes and JSON-derived report/gate
  30. output. It does not replace tests, CI, or human review.
  31. - **Validation:** 116 offline pipeline, NEWS, installation, bilingual, locale, and source-freshness tests; clean-project
  32. end-to-end gate runs; additional probe smokes. These are regression checks,
  33. not a general recall claim. Concurrency-defect detection has not been
  34. validated.
  35. For the next stable release, update `VERSION` (for example, to `0.1.1`) and push it to `main`. After Validate skills succeeds, the release workflow generates NEWS from commits, updates the README release information, and publishes the version tag and GitHub Release. Existing releases are preserved; failed CI does not publish.
  36. ## Contents
  37. - [Latest news](#latest-news)
  38. - [Release status](#release-status)
  39. - [Why this skill](#why-this-skill)
  40. - [Quick start](#quick-start)
  41. - [How it works](#how-it-works)
  42. - [Evidence contract](#evidence-contract)
  43. - [Configuration](#configuration)
  44. - [What this is not](#what-this-is-not)
  45. - [Validation](#validation)
  46. - [Requirements](#requirements)
  47. - [Repository layout](#repository-layout)
  48. - [Contributing](#contributing)
  49. - [License](#license)
  50. ## Why this skill
  51. **No self-grading.**
  52. The implementation context does not sign off on its own work. Four probes run in fresh contexts, each files its own evidence, and the gate is derived from those records.
  53. *This is separation of duties, not independent human adjudication; all probes still use the same model.*
  54. | | |
  55. |---|---|
  56. | **Static-first** | Works on a fresh clone or a partial checkout. Coverage is optional, not a prerequisite. |
  57. | **Evidence contract** | A finding without a location, summary, and checkable evidence is not a finding. |
  58. | **Four probes** | Behavior, tests, rules, and impact are separate questions with separate reports. |
  59. | **Machine-checkable gate** | Counts and blockers come from JSON, not from prose the model retyped. |
  60. | **Auditable output** | The human report and the JSON records are rendered from the same source and verified against each other. |
  61. ## Quick start
  62. ### Install
  63. Run this command **inside your project**:
  64. ```bash
  65. # English (default)
  66. npx -y skills add kyy-logs/code-review-gate-skill --agent codex --skill code-review-gate --yes
  67. # Chinese
  68. npx -y skills add kyy-logs/code-review-gate-skill --agent codex --skill code-review-gate-zh --yes
  69. ```
  70. Use `--agent claude-code` for Claude Code. Codex installs to `.agents/skills/<skill>/`; Claude Code installs to `.claude/skills/<skill>/`. Node.js 22.20+ is required. Install one language per project. The Python installers also accept `--lang en|zh-CN` and default to English.
  71. ### Run
  72. Ask in Claude Code:
  73. ```text
  74. Review these changes with code-review-gate.
  75. ```
  76. Or invoke the skill directly:
  77. ```text
  78. /code-review-gate
  79. ```
  80. For a fixed range:
  81. ```text
  82. Use code-review-gate on commits abc123..def456
  83. ```
  84. The skill supports two review modes:
  85. - `worktree` — staged, unstaged, and untracked changes against the current `HEAD`.
  86. - `commits` — a fixed `base..head` range.
  87. ### Read the result
  88. ```text
  89. docs/work/active/{slug}/
  90. ├── code-review.md # human report
  91. ├── review-snapshot.json
  92. └── probes/
  93. ├── behavior-review.json
  94. ├── test-coverage.json
  95. ├── repo-guard.json
  96. └── impact-analysis.json
  97. ```
  98. ## How it works
  99. <p align="center">
  100. <img src="assets/code-review-architecture.svg" width="1160" alt="Four fresh-context probes run in parallel and write their own JSON; the main executor syncs, reconciles high findings, renders the report, and applies the gate.">
  101. </p>
  102. The four probes use the same model in fresh contexts. This is separation of duties, not independent human review. A passing gate is not human approval, CI, or proof that no issues remain. The current skill has no separate reviewer or finding-verification stage; raw findings feed the report and gate.
  103. 1. **Scope** — determine `worktree` or `commits`; record base and head as commit IDs, then init the run with `--mode` to pin `review-snapshot.json`.
  104. 2. **Probes** — dispatch four independent agents with the same scope and diff, each writing its own probe JSON. Run in batches if host capacity is limited, or record a serial fallback if agents are unavailable. Cross-probe duplicates are retained and counted; actual speed and token savings remain unverified.
  105. 3. **Sync** — validate probe JSON and derive counts with `collect-metrics`.
  106. 4. **Reconcile** — high findings must be closed or marked false-positive by the probe.
  107. 5. **Report** — render the human report’s fact sections from JSON, then verify them.
  108. 6. **Gate** — source freshness, required-probe failures, and open high findings block the merge.
  109. ### The four probes
  110. | Probe | Required | Question it answers |
  111. |---|---|---|
  112. | `behavior-review` | yes | Does the changed behavior match its actual contract and implementation path? |
  113. | `test-coverage` | yes | Are the tests meaningful, and is incremental coverage measured when data exists? |
  114. | `repo-guard` | yes | Does the change violate repository or project rules? |
  115. | `impact-analysis` | no | Who calls this, what contracts change, and what is the performance/architecture blast radius? |
  116. Probes are intentionally narrow. `behavior-review` is not a linter, and `repo-guard` is not a general bug scanner.
  117. ### Language and stack coverage
  118. The default `repo-guard` workflow selects `.java`, `.ts`, `.tsx`, and `.vue` files for pattern scanning. The built-in rule pack includes Java- and Spring-specific guidance; selecting an extension does not establish complete framework or language coverage.
  119. AI semantic checks can inspect relevant code beyond those extensions, but their results depend on the model and available contracts, source, and tests. The historical cases below exercise particular stacks and skill snapshots; they do not establish equally validated support across all stacks. Use applicable project rules and record unverified dependencies or language-specific behavior.
  120. ## Evidence contract
  121. Every finding records:
  122. | Field | Meaning |
  123. |---|---|
  124. | `location` | `path:line`, or file level with a reason |
  125. | `summary` | What is wrong — not “consider improving” |
  126. | `evidence` | Contract, code path, test output, or rule ID |
  127. | `severity` | `high` / `medium` / `low` |
  128. | `status` | `open` / `reconciled` / `wontfix` / `false-positive` |
  129. High-severity findings must cite the actual method signature and the contract they violate, or a concrete code path. A hunch is capped at `medium` until the evidence is checked.
  130. ## Configuration
  131. `references/probes.yaml` controls the probe registry:
  132. Project-specific rules can live in `.code-review/rules/`, or be pointed to with `CODE_REVIEW_RULES_DIR`:
  133. ```bash
  134. export CODE_REVIEW_RULES_DIR=/path/to/rules
  135. ```
  136. A project rule package **replaces** the built-in package; it is not merged with it.
  137. ## What this is not
  138. - Not a replacement for tests, CI, or human review.
  139. - Not a guarantee that a clean report means the change is correct.
  140. - Not a coverage tool: coverage is used when provided, not required.
  141. - Not a fixer: it does not modify the code under review.
  142. ## Validation
  143. Offline tests check JSON validation, derived counts, report consistency, installation, and gate behavior. Passing them does not establish defect-detection recall, false-positive rates, or the correctness of an AI finding.
  144. A controlled comparison against a single-agent review, measuring missed defects, false positives, wall-clock time, and token usage on the same cases and model configuration, has not yet been established. The historical runs below are snapshot-specific observations and do not demonstrate an improvement over that baseline.
  145. <details>
  146. <summary>11-case historical Java regression (2026-10-29)</summary>
  147. - Baseline: commit `494a39bb`, before `behavior-review` was extracted into a standalone probe. The snapshot validates the shared finding and gate contract, not the four-probe split itself.
  148. - 11/11 cases completed; static review.
  149. - Original behavior targets: 5/5 hit; including two independently confirmed edge cases, 5/7 required targets were found.
  150. - Clean and fixed controls: 4/4 passed without false blocking.
  151. - Two confirmed edge-case misses remain: legal input formatting in a parser, and a JSON representation round-trip in command rendering.
  152. - 33 raw findings: 8 high, 20 medium, 5 low; 0 confirmed false positives, with unverified items still open.
  153. - The full merge gate was not run.
  154. Risk areas exercised by these cases:
  155. | Risk area | Cases | Observed result |
  156. |---|---|---|
  157. | Resource lifecycle | DBeaver | Found an input stream left open after copying; confirmed target. |
  158. | Execution logic | Kestra, Keycloak guides | Found duplicate interpreter/command assembly in Kestra; confirmed target. Also reported switch fall-through in Keycloak, with downstream impact only partly supported. |
  159. | Input boundaries and value handling | Lang-1, Spring AI Alibaba | Found hexadecimal overflow handling and blank-string sentinel problems; confirmed targets. The leading-zero return-type finding remained a contract dispute and was rated too high. |
  160. | Permissions and data scope | Keycloak groups (m01), Elasticsearch | Found authorization resource IDs used as group IDs; confirmed target. The non-default filesystem permission-bypass candidate still needs threat-model and exploitability evidence. |
  161. | API compatibility | Kestra | Identified public SPI return-type changes and new abstract methods; compatibility break supported, affected external plugins not measured. |
  162. | Cache and state consistency | Keycloak login cache (m02) | Reported an invalidation risk involving organization-wrapped models; runtime consequences remain unverified. |
  163. | Performance and repeated work | Elasticsearch, Kestra, Keycloak login cache | Reported logging overhead, repeated rendering/downloads, and extra lookups; performance impact was not benchmarked. |
  164. | Test quality and regression protection | DBeaver, Keycloak, Kestra | Identified missing branch tests, tests bypassing the changed production entry point, and incorrect cleanup or cache-invalidation coverage. |
  165. The two confirmed misses were Keycloak's valid `tileVisible = "false"`
  166. syntax bypassing validation, and Kestra's JSON render/parse round-trip
  167. corrupting command values containing quotes, backslashes, or newlines.
  168. The four controls checked false alarms: the Lang-1 fix, normal pagination,
  169. normal tag normalization, and a valid login-cache delegation path that should
  170. not be reported as recursion. Passing a control does not establish that its
  171. entire change is defect-free.
  172. The evaluation harness and raw reports are kept out of the published repository. This snapshot is a regression result, not a claim of general recall.
  173. </details>
  174. <details>
  175. <summary>9-case expansion (2026-10-30)</summary>
  176. - Separate run `2026-10-30-review9-1a4adc1` on an older `main` (`1a4adc1`); it did not re-run the 11 historical cases. Do not combine the two batches into a 20/20 claim.
  177. - 9/9 cases completed; 36/36 probe records; 0 probe errors or skipped cases.
  178. - Positive targets: 4/6. Fixed controls: 3/3 stopped reporting.
  179. - 22 raw findings: 7 high, 13 medium, 2 low. This older run used the reviewer (5 run / 4 skip); the current skill has no independent reviewer.
  180. - Confirmed misses: x01's legal `d` flag and x04's cancellation/loading lifecycle.
  181. - Severity or contract caveats remain for several cases, including x02, x05, x06, and x08; this is not a general recall claim.
  182. </details>
  183. ## Requirements
  184. - Claude Code with Agent Skills support, or Codex with custom-agent support.
  185. - Bash 3.2+, Git, awk, grep, sed (macOS: invoke with `/bin/bash`; Linux/Windows Git Bash: `bash`).
  186. - Python 3.9+ is required to run the review scripts; PyYAML is used for report parsing and metrics.
  187. - Node.js 22.20+ is required for the `npx skills` install entry.
  188. ## Repository layout
  189. ```text
  190. code-review-gate-skill/
  191. ├── README.md
  192. ├── README.zh-CN.md
  193. ├── NEWS.md
  194. ├── LICENSE
  195. ├── VERSION
  196. ├── assets/
  197. │ ├── code-review-architecture.svg
  198. │ └── code-review-architecture.zh-CN.svg
  199. ├── .github/workflows/
  200. │ ├── news-update.yml
  201. │ ├── skill-validation.yml
  202. │ ├── star-history.yml
  203. │ └── sync-news.yml
  204. ├── scripts/
  205. │ ├── check-skill-locales.py
  206. │ ├── install
  207. │ ├── install.py
  208. │ ├── install-remote.py
  209. │ ├── news-update.py
  210. │ ├── sync-skill-scripts.py
  211. │ └── sync-news.py
  212. ├── shared/scripts/
  213. │ ├── collect-metrics
  214. │ ├── lib-metrics
  215. │ ├── rule-grep
  216. │ └── sync-results.py
  217. ├── skills/
  218. │ ├── code-review-gate/
  219. │ │ ├── SKILL.md
  220. │ │ ├── assets/
  221. │ │ ├── references/
  222. │ │ └── scripts/
  223. │ └── code-review-gate-zh/
  224. │ ├── SKILL.md
  225. │ ├── assets/
  226. │ ├── references/
  227. │ └── scripts/
  228. └── tests/
  229. ```
  230. ## Star history
  231. [![Star History Chart](https://raw.githubusercontent.com/kyy-logs/code-review-gate-skill/star-history/star-history.svg)](https://star-history.com/#kyy-logs/code-review-gate-skill&Date)
  232. Updated daily by [`star-history.yml`](.github/workflows/star-history.yml).
  233. ## Contributing
  234. Issues and pull requests are welcome. For a behavior change, include the review target (repo and base/head), expected and observed result or gate decision, and evidence that distinguishes them.
  235. For a probe or schema change, update the probe document, output contract, and affected scripts together.
  236. Run tests with `python -m unittest discover -s tests -v`; set `CODE_REVIEW_TEST_BASH` to include shell and installation checks. These tests do not call models or establish defect recall.
  237. For user-facing changes, add an entry to `NEWS.md`. Pushes to `main` update the README news preview; locally, run `python scripts/news-update.py` and `python scripts/sync-news.py` (use `--check` to verify only). Keep the Chinese README aligned.
  238. ## License
  239. This repository is distributed under the [MIT License](LICENSE).
  240. ## Project policy and output
  241. Optional `.code-review/config.json` (paths relative to the reviewed project):
  242. ```json
  243. {
  244. "output_dir": "docs/work",
  245. "line_target": 85,
  246. "branch_target": 80
  247. }
  248. ```
  249. 85% / 80% are configurable defaults. Line coverage blocks below target; branch coverage is advisory.
  250. Probes, gates, and reports use the same effective targets. `CODE_REVIEW_OUTPUT_DIR` overrides the output root;
  251. pass identical settings to every shell invocation. Source inspection is read-only, but the workflow writes
  252. `active/<slug>/code-review.md`, `probes/*.json`, `review-snapshot.json`, root-level `workflow-events.log`,
  253. and scorecards / `quality-trend.csv` on archive.
  254. Start a new review with `bash "$CODE_REVIEW_SKILL_DIR/scripts/collect-metrics" init <unique-slug> --mode worktree`
  255. (or `--mode commits --base <base> [--head <head>]`). With `--mode`, init writes `review-snapshot.json`; new runs
  256. should always pass it. Omitting `--mode` keeps the legacy behavior and skips freshness checking.
  257. Existing active, archived, or event-history slugs are rejected. Re-rendering the same run updates only automatic report regions;
  258. do not run concurrent writers for the same run. The effective thresholds are returned by `init` and recorded in the generated report; keep configuration stable when
  259. resuming, and re-check findings and re-render after policy changes. `gate-pass code-review` recomputes `review-snapshot.json`
  260. and returns `stale-review` when the reviewed source changed; run `snapshot <slug>` after a fix and re-review.
  261. The minimum shell is Bash 3.2. macOS can use `/bin/bash`; Linux / Windows Git Bash use `bash`.
  262. A macOS CI job is configured; a passing macOS result has not been established locally.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.