qoq-code-review

A Claude Code Agent Skill that turns a branch review into a set of small, reviewable, revertible improvements rather than a wall of prose the author has to re-implement by hand. It diffs the branch against a base, runs the QoQ analyses, and stages each suggestion as its own git patch — validated against the project's own lint/test/build before the next one lands.

The guiding value is QoQ — quality over quantity: a few high-confidence, intention-revealing changes beat a long list of nitpicks. An empty result for a dimension is a fine result.

Installation

skills CLI

Vercel's skills CLI pulls the skill straight from the repo into your project's .claude/skills/:

npx skills add ladamczyk-it/qoq --skill qoq-code-review

Add --global to install it to your user directory instead, or --agent claude-code to target Claude Code explicitly.

agent-skills-cli

agent-skills-cli is a universal installer that targets Claude Code and many other agents. Both CLIs expose a skills binary, so invoke this one through its agent-skills bin to avoid the name clash:

npx -p agent-skills-cli agent-skills add ladamczyk-it/qoq@qoq-code-review -a claude

Add -g to install globally to ~/.claude/skills/.

Claude Code plugin marketplace

The skill ships in the qoq-agent-skills plugin marketplace, inside the code-quality-skills plugin — which bundles this skill together with qoq-code-refactor, since the refactor skill reuses this one's analysis engine. Add the marketplace and install the plugin from within Claude Code:

/plugin marketplace add ladamczyk-it/qoq
/plugin install code-quality-skills@qoq-agent-skills

Once installed, Claude loads the skill automatically — no further setup.

When it triggers

Claude reaches for this skill whenever you ask to "review my changes/branch/diff/PR", want a code review before merging, or ask it to check code quality, naming, dead dependencies, duplication, or complexity — including phrasings like "is this ready to merge" or "clean up this branch". You don't have to say the words "code review".

It is the local, hands-on reviewer, distinct from the cloud multi-agent code-review skill.

How it works

The workflow separates planning from executing, to defeat two failure modes: review that never lands (feedback silently dropped because re-typing it is tedious — the antidote is shipping ready-to-apply patches) and unattributable breakage (applying many edits at once so you can't tell which one broke the build — the antidote is one-category-at-a-time application with validation in between).

Phase	What happens
1 · Discovery	Confirm a clean tree, ask for the base branch, scope the diff against the merge-base, detect the QoQ tier, and verify a green baseline.
2 · Analysis	Run the seven dimensions, each producing one git apply-able patch with the minimum change — written to the project's own standards.
3 · Present plan	Summarize each finding and patch size for sign-off; let the user drop or adjust patches.
4 · Execution	Apply approved patches lowest-risk first, validating after each; regenerate (never force) a patch that stops applying.
5 · Readability	Format the changed files, run a final validation pass, then remove the workspace and revert the temporary .gitignore entry.

Every change is staged in a .qoq-code-review/ workspace as a git patch, generated with an edit → diff → restore → check recipe so the working tree stays clean until you approve execution.

The seven dimensions

Each analysis yields at most one patch; a dimension with nothing worth changing is skipped.

Dimension	What it looks for	Patch file
Spelling & naming	Typos, naming conventions, intention-revealing names, no single-letter vars, destructuring	spellings.patch
Dependencies	Unused deps/exports and mis-placed runtime vs. dev dependencies	dependencies.patch
Complexity / SOLID	Cognitive complexity and SOLID violations that a small restructuring genuinely simplifies	complexity.patch
Copy-paste	Near-duplicate logic worth extracting into one honest abstraction	copy_paste.patch
Code conventions	House style — arrow functions over function, named exports over default	conventions.patch
Design patterns	Code smells a standard pattern resolves without adding more complexity than it removes	patterns.patch
TypeScript idioms	Target-appropriate syntax, immutable array/object methods, honest types (no any)	typescript.patch

The TypeScript dimension is skipped for plain-JavaScript changes, and several conventions are anchored to the project's real tsconfig.json target rather than guessed.

Tooling — three tiers

The skill works on any JS/TS project, preferring the highest tier available:

1. The qoq CLI (preferred) — when @ladamczyk/qoq-cli is installed and a qoq.config.js sits at the root. Every analysis is driven through qoq, so it measures against the same rules the project enforces in CI. A single qoq --json --output …/reports primes ESLint/Knip/JSCPD/Prettier reports for the report-backed dimensions to read.
2. The project's own tools (fallback) — Prettier/ESLint/Knip/JSCPD via the project's own scripts.
3. Ad-hoc npx (last resort) — run a missing tool with npx, and suggest the project adopt it (or the matching @ladamczyk/qoq-* config / the qoq CLI).

Allowed tools

The skill is sandboxed to the commands it actually needs:

Bash(npm run:*)
Bash(qoq:*)
Bash(npx qoq:*)
Bash(mkdir -p .qoq-code-review)
Bash(git diff:*)
Bash(git merge-base:*)
Bash(git apply:*)
Bash(git restore:*)
Bash(git status:*)
Bash(git log:*)

Relationship to qoq-code-refactor

qoq-code-refactor runs the exact same seven analyses, tooling tiers, and patch conventions — but over a user-chosen scope (a path, a package, or the whole project) instead of a branch diff, and it can fan the work out across subagents. Reach for qoq-code-review to vet what a branch changed against its base; reach for the refactor skill to improve an existing area or the whole codebase on demand.