Code Review Skill for Claude Code

Multi-specialist code review system for Claude Code. Dispatches up to 18 specialist AI reviewers in parallel, integrates external linters and analyzers, and produces structured reports with a GO / NO-GO verdict.

Auto-detects your tech stack (TypeScript, Python, Go, Rust, Java/Kotlin, Scala) and activates only the relevant reviewers, overlays, and tools.

Quick Start

# Install into your project
npx @ctxr/kit install @ctxr/skill-code-review

Then in Claude Code:

/skill-code-review

Prerequisites

• Claude Code CLI or IDE extension
• Git repository with commits to review

Installation

Manual

git clone https://github.com/ctxr-dev/skill-code-review.git /tmp/skill-code-review
mkdir -p .claude/skills
cp -r /tmp/skill-code-review .claude/skills/skill-code-review

Git Submodule

git submodule add https://github.com/ctxr-dev/skill-code-review.git \
    .claude/skills/skill-code-review

Usage

/skill-code-review                                # diff review, auto-detect everything
/skill-code-review help                           # show all arguments
/skill-code-review full                           # review entire codebase
/skill-code-review mode=thorough                  # max depth within detected stack
/skill-code-review format=json                    # structured JSON output
/skill-code-review tools=interactive              # ask to install missing linters
/skill-code-review scope-dir=src/api              # only review src/api/
/skill-code-review scope-reviewer=security        # only security specialist
/skill-code-review base=origin/main head=HEAD     # explicit commit range

See report-format.md for the full argument reference, output examples, and JSON schema.

How it works

1. Scan — detects languages, frameworks, monorepo structure from manifests
2. Tools — discovers and runs external linters/analyzers (eslint, semgrep, mypy, clippy, etc.)
3. Route — reads reviewers/index.yaml to select specialists deterministically
4. Overlay — loads framework-specific checks for detected tech (React, Prisma, Django, Docker, etc.)
5. Dispatch — all selected specialists run in parallel with filtered diffs + tool output
6. Verify — every file reviewed by at least 2 specialists
7. Verdict — 8-gate release readiness: GO / NO-GO / CONDITIONAL

Reviewers

7 universal (always active): clean-code-solid, architecture-design, test-quality, security, error-resilience, initialization-hygiene, release-readiness

11 conditional (activated by signals): language-quality, concurrency-async, performance, dependency-supply-chain, documentation-quality, data-validation, api-design, observability, cli-quality, hooks-safety, readme-quality

27 overlays (loaded per framework): 17 frameworks, 6 languages, 4 infrastructure

See SKILL.md for full specialist descriptions.

Report Format

Every review produces (markdown or JSON):

• Release Verdict — GO / NO-GO / CONDITIONAL
• SOLID Compliance — principle-by-principle status
• Issues — clickable file:line links, severity, specialist, impact, fix
• Tool Results — pass/fail/skipped for each external linter/analyzer
• Specialist Results — per-reviewer status with issue counts
• Release Gates — 8-gate assessment
• Coverage Matrix — files × specialists

Architecture

skill-code-review/
├── SKILL.md                  # Skill metadata and overview
├── code-reviewer.md          # Orchestrator (reads index for routing)
├── report-format.md          # Canonical report format + JSON schema + argument spec
├── reviewers/
│   ├── index.yaml            # Auto-generated from reviewer frontmatter
│   ├── clean-code-solid.md   # Each reviewer has YAML frontmatter (tools, audit_surface)
│   ├── security.md
│   └── ... (18 reviewers)
└── overlays/
    ├── index.md              # Overlay routing table
    ├── frameworks/           # 17 framework overlays (some with tool declarations)
    ├── languages/            # 6 language overlays (all with tool declarations)
    └── infra/                # 4 infrastructure overlays (some with tool declarations)

Customization

Add a framework overlay

1. npm run new:overlay -- frameworks <name>
2. Fill in the checklist items and optional tools frontmatter
3. Add row to overlays/index.md
4. npm run validate && npm run lint

Add a reviewer

1. npm run new:reviewer -- <id>
2. Fill in frontmatter (tools, audit_surface, activation) and checklist
3. npm run index:build && npm run validate && npm run lint

Severity levels

• Critical — must fix, blocks merge (security, data loss, correctness)
• Important — should fix, blocks merge (SOLID violation, missing tests)
• Minor — advisory, does not block (naming, style)

Contributing

See CONTRIBUTING.md for setup and conventions.

Releasing

Releases are PR-gated. Version bumps land on main through a review gate like any other change; only the tag push is automated.

One-time setup

Enable these on the repo before your first release:

• Repository secret NPM_TOKEN set to an npm access token with publish rights on the @ctxr scope (npm token create).
• Settings → Actions → General → Workflow permissions: enable Allow GitHub Actions to create and approve pull requests so release.yml can open its version-bump PR with GITHUB_TOKEN. If the checkbox is greyed out, an organization-level Actions policy is restricting it; ask an org admin to unlock the setting first.
• (Optional, recommended) GitHub-managed CodeQL default setup: Security → Code security → enable default setup for javascript-typescript and actions.
• (Optional) A branch ruleset on main requiring PR review + code scanning. The release flow works without it; gates are strictly stricter when enabled.

Cutting a release

1. Actions → Release → Run workflow.
   • Branch selector: main (the workflow refuses any other ref).
   • Version bump: patch / minor / major.
   • Click Run workflow.
2. The workflow bumps package.json on a fresh release/v<version> branch and opens a PR to main titled release: v<version>.
3. Review the PR (diff is just version fields). Approve + merge.
4. On merge, tag-on-main.yml fires automatically:
   • Detects the version change.
   • Creates and pushes the annotated v<version> tag via GITHUB_TOKEN.
5. Actions → Publish to npm → Run workflow on the v<version> tag. The workflow runs npm ci + index:build + validate + lint + test, verifies the tag matches package.json, and publishes the package to npm.

Why a manual dispatch for step 5? GitHub's built-in GITHUB_TOKEN cannot trigger further workflows (on: push: tags won't fire when a workflow pushed the tag). So the tag auto-creation stops at the tag. Publishing is one extra click. To make it fully automatic, swap the push credential in tag-on-main.yml for a GitHub App token or fine-grained PAT stored as a repo secret, then the push: tags trigger on publish.yml will fire and step 5 happens by itself.

From Run workflow on Release to published on npm is one dispatch + one PR merge + one dispatch (or one dispatch + one PR merge, once a PAT/App-token is wired in).

See GitHub Releases for the changelog.

Troubleshooting

• Release workflow fails with "dispatched from non-main ref" — you selected a feature branch in the Actions UI. Re-dispatch with main.

• tag-on-main fails with "Tag vX.Y.Z exists but points at …" — a stale/orphan tag from a prior failed release. Delete and re-run:

  git push origin --delete vX.Y.Z

  Then merge a trivial no-op PR to main (or revert-and-re-merge the release PR) to retrigger tag-on-main. Direct pushes to main may be blocked by branch protection, so the PR path is the reliable retrigger.

• publish.yml fails on "Verify version matches tag" — tag and package.json disagree. Investigate the merge commit; this should not happen under the PR-based flow.

• GitHub Actions is not permitted to create pull requests — org or enterprise policy blocks the GITHUB_TOKEN from opening PRs. Enable Allow GitHub Actions to create and approve pull requests at the org level (Settings → Actions → General → Workflow permissions), or ask the enterprise admin to unlock the setting.

License

MIT

Example

Prompt

Use code review global skill to review frontend