A composable suite of code-review skills, built from first principles — map everything that factors into code quality, then distill it into focused, single-purpose review lenses an AI coding agent can run.
It ships as a Claude Code plugin, but the skills are plain SKILL.md files with
no Claude-specific dependencies, so the suite also runs in any coding agent that
supports the SKILL.md format (Cursor, Windsurf, Copilot, …). The plugin wrapper
— commands, hooks, marketplace metadata — is additive.
Jump to: Install · Wire it into your repo · Use it · Automate PR review · How it was built
43 review skills, generated from a researched taxonomy and refined against eval scenarios:
- 40 review lenses — each a narrow, self-contained reviewer (correctness,
naming & readability, module design, concurrency, migrations & data safety,
security, performance, tests, API contracts, data transformations & data
contracts, accessibility & i18n, observability,
LLM-integration, agentic & tool-use safety, resilience, install/upgrade
experience, plus repo-shaped audits
for architecture, dependencies, config/build, docs, compliance,
infrastructure-as-code, decision-record currency, data-pipeline health, a
decision-time lens, and an
artifact lens that reviews authored artifacts like
SKILL.mdagainst their own standard, plus the first two Cluster VII lenses — usability & interaction quality and product-outcome instrumentation — and 12 more). Each leads with a one-line tagline, runs on its own, and carries its full checklist inreference/heuristics.md(the artifact lens uses artifact-specific rubric files instead); the narrowly-scoped lenses add an explicit Skip when… clause so the router knows when not to run them. choosing-review-lenses— a router that ranks a change's relevant lenses and runs the top few by default, with triage and comprehensive depth modes for fewer or all of them, so you don't have to know the catalog.grounding-review-in-tool-output— a pre-pass that runs the deterministic linters, type checkers, and scanners the reviewed repo already configures, scoped to what's under review, and hands each lens their hits as evidence to confirm, contextualize, or dismiss. It never introduces a tool the repo hasn't adopted, and a clean run clears nothing.synthesizing-review-findings— merges multiple lenses (and any other reviewer) into one deduplicated, severity-ranked, single-verdict report.
The catalog lives in skills/manifest.yaml. For Claude
Code, the plugin also adds slash commands, a side-effect-free SessionStart routing
hook, opt-in self-improvement telemetry hooks (off by default), and routing templates.
The point of the suite is to supersede the generic built-in /code-review (and
framework reviews like BMAD) as the primary review path — with deeper,
research-derived coverage — while still folding their findings in through the
synthesizer rather than picking only one.
Both paths install the same skills; the Claude Code plugin adds commands and hooks
on top. Update mechanics, web-session setup, and keeping current are in
docs/install.md.
Any SKILL.md agent — via Skulto
(recommended cross-platform path; syncs to Claude Code, Cursor, Windsurf, Copilot,
and 25+ more):
brew install asteroid-belt/tap/skulto
skulto add brandondees/code-quality-atlas
skulto install brandondees/code-quality-atlas -yClaude Code (plugin):
/plugin marketplace add brandondees/code-quality-atlas
/plugin install code-quality-atlas@code-quality-atlas
The plugin and the .claude/settings.json marketplace snippet are CLI-local —
they do not load in Claude Code web/cloud sessions (the cloud runtime
doesn't run the plugin-install step). For cloud, enable the suite as account
skills on claude.ai or vendor .claude/skills/ into the repo — see
docs/distribution.md.
Installing the suite makes it available; it doesn't guarantee an agent reaches
for it. On a plain "review this," the shorter-named built-in code-review can win
the keyword race. The deterministic fix is a routing block in the repo's
CLAUDE.md / AGENTS.md — agents read it at session start, and it outranks
keyword matching.
In a Claude Code session inside the repo you want reviewed:
/code-quality-atlas:atlas-init
It writes an idempotent routing block into both CLAUDE.md and AGENTS.md (different
agents read different files), telling them to prefer the atlas suite over
/code-review and framework reviews — combined non-exclusively. Not on Claude Code?
Paste templates/agents-routing-snippet.md by
hand.
The plugin also ships a SessionStart hook that nudges agents toward the suite each
session — a backstop for when skill descriptions get budgeted out of context — plus a
pair of opt-in, off-by-default hooks that feed the suite's self-improvement loop when a
repo turns them on. Details in docs/install.md.
Most of the time you want one command. Built a feature and want it reviewed? Run
/atlas-review-pr <pr> if it's a pull request, or /atlas-code-review for
local or pushed-branch changes with no PR. That's the whole happy path — the command
picks the lenses your change actually needs — a few by default, or every relevant
one in comprehensive mode — and merges their findings into one ranked verdict for
you. You don't pick lenses by hand or run the synthesizer
yourself; reach for an individual lens (the rows below) only when you already know
which one you want. If you ran a command and got useful feedback, you used it right.
| Situation | Reach for |
|---|---|
| A whole PR | /atlas-review-pr |
| Local changes with no PR (working tree, or a pushed branch) | /atlas-code-review |
| By hand, unsure which lenses apply | choosing-review-lenses (ranks the change's relevant lenses; top few by default) |
| The relevant lens is obvious | call it directly (async change → reviewing-concurrency-and-async) |
| You ran more than one lens | finish with synthesizing-review-findings |
| Many repos at once | the multi-repo audit runbook |
Every lens runs on its own; its SKILL.md is self-sufficient for a first pass and
reference/heuristics.md holds the full checklist.
The plugin turns the suite into a hands-off pull-request loop on Claude Code on the web: a GitHub-event reviewer that re-reviews each push and quiets down as it converges, plus a scheduled poller that rebases stale PRs and pokes conflicts (the gap GitHub webhooks don't cover). Convergence rules — a severity floor that settles at Major, comments only for genuinely-new findings, approve-on-clean, and a round cap — keep the reviewer and a build/auto-fix session from ping-ponging forever.
The commands ship with the plugin; the routines are account-side config you create
once. Step-by-step setup:
docs/runbooks/pr-review-automation.md.
Copy templates/REVIEW.md into the reviewed repo to tune the
convergence policy.
Built fresh from first principles, treating existing skills, linters, and review
tools as prior art to learn from — not constraints. Docs are the source of truth;
skills are generated from skills/manifest.yaml with
provenance hashes, a drift-checker, and eval-first refinement. The underlying map is
a broad, layered taxonomy — clusters of quality categories, each decomposed into
concrete factors — that every skill traces back to. Ongoing work is the compounding
loop: critique the research, let drift flag affected skills, regenerate, re-gate.
- Project intent, scope, phases, principles →
docs/overview.md - The master map →
docs/taxonomy.md; per-cluster research →docs/research/ - Architecture & generation →
docs/phase-2-skill-suite-design.md; regenerating skills - Decisions & history →
docs/open-questions.md;docs/session-log.md; structural gaps →docs/map-gaps.md - Prior art surveyed →
docs/prior-art.md - Contributor system map (what a change hits) →
docs/map/CLAUDE.md
| Path | What's in it |
|---|---|
skills/ |
The 40 lenses + the three composition skills: choosing-review-lenses (router), grounding-review-in-tool-output (tool-grounding pre-pass), synthesizing-review-findings (synthesizer) |
collapsed/ |
Generated 4-entrypoint form of the suite for cloud / account-skill installs; each entrypoint bundles its shape's lenses and loads them on demand |
commands/ |
Slash commands: /atlas-review-pr, /atlas-code-review, /atlas-init, /atlas-rebase-stale, /atlas-propose-preferences |
hooks/ |
SessionStart routing hook (side-effect-free); opt-in, off-by-default PostToolUse/SessionEnd self-improvement telemetry hooks |
templates/ |
REVIEW.md convergence policy + agents-routing-snippet.md routing block + preferences-template.md team-preferences bootstrap |
tooling/ |
The pipeline: generator, drift-checker, eval validator, cross-model runner |
docs/ |
Research, taxonomy, design, runbooks, install guide, decision log |
Dual-licensed by content type: the research atlas and skills (docs/, skills/,
collapsed/, commands/, templates/, this README) are CC BY 4.0
— reuse freely with attribution; the pipeline code (tooling/, hooks/, tests/,
CI/config) is MIT. Details in LICENSE.