qoq-code-refactor
A Claude Code Agent Skill that applies the QoQ code-quality analysis to a scope you choose — one or more paths/globs, a monorepo package, a directory, or, by default, the whole project — rather than to the changes a branch introduced. It uses no base branch and no diff.
It is the broad, scope-driven sibling of qoq-code-review. For large scopes it runs as an orchestrator: it fans the analysis out across subagents by code area, gathers every staged git patch, regroups them, and applies them one at a time behind the project's own lint/test/build.
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-refactor
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-refactor -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 it together with its dependency qoq-code-review. Installing the plugin satisfies the dependency in one step:
/plugin marketplace add ladamczyk-it/qoq
/plugin install code-quality-skills@qoq-agent-skills
Once installed, Claude loads the skill automatically — no further setup.
:::note Requires qoq-code-review
qoq-code-refactor does not redefine the analysis — it reads qoq-code-review's SKILL.md as its single source of truth and overrides only the scoping and fan-out. That skill is a mandatory dependency: install it alongside (the code-quality-skills plugin bundles both), or the refactor skill will stop and ask you to add it before running.
:::
When it triggers
Claude reaches for this skill whenever you want to "clean up / refactor / tidy / improve / modernize" a file, folder, package, or the whole codebase, or ask it to "reduce complexity", "remove dead dependencies", "de-duplicate", "fix naming", or "apply our quality standards to <area>" — even when there is no branch to review and even if you don't say the word "refactor".
How it works
The skill is a thin layer over qoq-code-review that changes two things: where the work comes from (a user-chosen scope, not a branch diff) and how it's carried out at size (an orchestrator that fans the analysis across subagents by code area). Everything else — the clean-tree check, QoQ-tier detection, the seven dimensions and their tooling, the edit→diff→restore→check patch recipe, the design-pattern catalog, and the apply/validate loop — it inherits unchanged. When the review skill's standards evolve, this one inherits the change automatically; there is nothing to keep in sync.
| Phase | What happens |
|---|---|
| 0 · Load engine | Read qoq-code-review's SKILL.md in full — the canonical analysis definition. Stop and ask for it if it isn't installed. |
| 1 · Scoping | Keep the clean-tree check, QoQ-tier detection, and green baseline; replace base-branch/diff with scope resolution to an explicit file list. |
| 2 · Orchestration | Small scope → run the seven dimensions yourself. Broad scope + approval → divide into disjoint code-area slices, brief one subagent each. |
| 3 · Present plan | Aggregate findings across slices, lead with the highest-value changes, and let trivial nitpicks be opted in or out wholesale. |
| 4 · Execution | Apply by dimension, lowest-risk first, aggregating each dimension's patches across all slices, validating after each. |
| 5 · Cleanup | Format, run a final validation pass, remove the .qoq-code-refactor/ workspace, and revert the temporary .gitignore entry. |
The orchestrator model
When the scope is broad and you approve subagents, the skill becomes a coordinator rather than doing the per-file analysis itself:
- Prime shared reports once (in QoQ mode) so subagents read JSON instead of each re-running linters across the whole project.
- Divide the scope into disjoint slices along natural seams (a package, directory, or coherent module). The cardinal rule: no two slices share a file — disjoint ownership is what lets subagents use the edit→restore patch recipe without trampling each other.
- One subagent per slice runs all seven dimensions on its files, in an isolated worktree, writing patches into its own subdirectory.
- Cross-cutting work stays with the orchestrator — project-wide unused dependencies and cross-slice copy-paste can't be seen from inside a single slice, so it owns those itself.
- Collect and regroup every returned patch by dimension for execution.
Allowed tools
The skill is sandboxed to the commands it actually needs:
Task
Bash(npm run:*)
Bash(qoq:*)
Bash(npx qoq:*)
Bash(mkdir -p .qoq-code-refactor)
Bash(git diff:*)
Bash(git apply:*)
Bash(git restore:*)
Bash(git status:*)
Bash(git stash:*)
Bash(git log:*)
Bash(git ls-files:*)
Relationship to qoq-code-review
Same standards by construction — this skill reuses qoq-code-review's analysis engine rather than redefining it. Use the review skill to vet a branch before merge; use this one to improve a chosen area or the whole project on demand.