code-quality-review
Skill3 starsChanged 3 days agoMITView on GitHub
Run an unusually strict structural code-quality review — not a correctness review. Use when the user wants a diff, commit, PR, or codebase reviewed for structure and maintainability: abstraction quality, giant files, spaghetti conditionals, and whether a restructuring could delete complexity while preserving behavior.
23 other projects use a version of this.
Adopted by
Most recently taken up by
- jellydn/my-ai-toolstheir own version, first seen Nov 15, 2026
- AthenDrakomin-hub/agent-skillstheir own version, first seen Nov 1, 2026
- damacus/agent-skillstheir own version, first seen Nov 1, 2026
- NovruzAliyevDev/skillstheir own version, first seen Nov 1, 2026
- VersoXBT/claude-recommended-skillstheir own version, first seen Oct 15, 2026
- paiml/aprendertheir own version, first seen Oct 8, 2026
Used with
Projects with it also use dependency-cve-sweep, fleet-standard-adoption and 6 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
berntpoppSkilldependency-cve-sweep
Use when handling Dependabot PRs, CodeQL/Trivy alerts, or doing a routine dependency/CVE sweep for this repo.
Also in 12 projects that use this
berntpoppSkillfleet-standard-adoption
Use when bringing this repo into compliance with a GeneFoundry fleet standard (tool-naming, response-envelope, container-hardening, versioning, MCP transport, or logging) or closing its tracking issue.
Also in 12 projects that use this
IgorGanapolskySkillci-failure-triage
Triage a CI / PR check failure by READING the failure body before forming any hypothesis. Triggered whenever a required check is red, a PR is BLOCKED, a merge won't land, or you're about to call a failure "transient", "flaky", "stale", or "orphaned". Prevents dismissing a real failure (e.g. real CodeQL security alerts) as noise.
Also in 12 projects that use this
Microsoft AzureSkillrelease-readiness
Complete ODIN release documentation and validation checks before declaring user-visible work complete, preparing a release, or opening the Release-to-main pull request.
Also in 12 projects that use this
SentrySkillsecurity-review
Finds exploitable application security vulnerabilities in code changes. Use for Warden security scans, appsec review, OWASP-style checks, authentication or authorization bugs, injection, XSS, SSRF, path traversal, secrets, unsafe crypto, webhook verification, open redirects, or sensitive data exposure.
Also in 13 projects that use this
AWSSkillretro
Conduct a retrospective on a coding session.
Also in 3 projects that use this
- +2 more from berntpopp
Other versions23 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 23
- paiml/aprender★ 137same name
- jellydn/my-ai-tools★ 129same name
- 535803710/ai-rd-skills★ 8same name
- berntpopp/genefoundry-router★ 7same name
- NovruzAliyevDev/skills★ 4same name
- VersoXBT/claude-recommended-skills★ 4same name
- damacus/agent-skills★ 2same name
- berntpopp/hpo-link★ 1same name
- berntpopp/mgi-link★ 1same name
- berntpopp/stringdb-link★ 1same name
13 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
44 rules. 0 are common, 43 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 18 edited versions we read keep these.
43
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Use this skill for an unusually strict review focused on implementation quality, maintainability, abstraction quality, and codebase health.
- Distinctive: line 14
Start from this baseline:
- Distinctive: line 27
Do not stop at "this could be a bit cleaner."
- Distinctive: line 28
Look for opportunities to reframe the change so that whole branches, helpers, modes, conditionals, or layers disappear entirely.
- Distinctive: line 29
Prefer the solution that makes the code feel inevitable in hindsight.
- Distinctive: line 31
If you see a path to delete complexity rather than rearrange it, push hard for that path.
- Distinctive: line 34
Treat this as a strong code-quality smell by default.
- Distinctive: line 35
Prefer extracting helpers, subcomponents, modules, or local abstractions instead of letting a file sprawl past 1000 lines.
- Distinctive: line 36
If the diff or existing file crosses that threshold, explicitly ask whether the code should be decomposed first.
- Distinctive: line 37
Only waive this if there is a compelling structural reason and the resulting file is still clearly organized.
- Distinctive: line 41
If a change adds "weird if statements in random places", treat that as a design problem, not a stylistic nit.
- Distinctive: line 42
Prefer pushing the logic into a dedicated abstraction, helper, state machine, policy object, or separate module instead of tangling an …
- Distinctive: line 43
Call out changes that make the surrounding code harder to reason about, even if they technically work.
- Distinctive: line 46
If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version.
- Distinctive: line 47
Do not rubber-stamp "it works" implementations that leave the codebase messier.
- Distinctive: line 51
Treat brittle, ad-hoc, or "magic" behavior as a code-quality problem.
- Distinctive: line 57
Prefer explicit typed models or shared contracts over loosely-shaped ad-hoc objects.
- Distinctive: line 58
If a branch relies on silent fallback to paper over an unclear invariant, ask whether the boundary should be made explicit instead.
- Distinctive: line 61
Call out feature logic leaking into shared paths or implementation details leaking through APIs.
- Distinctive: line 62
Prefer existing canonical utilities/helpers over bespoke one-offs.
- Distinctive: line 66
If independent work is serialized for no good reason, ask whether the flow should run in parallel instead.
- Distinctive: line 67
If related updates can leave state half-applied, push for a more atomic structure.
- Distinctive: line 68
Do not over-index on micro-optimizations, but do flag avoidable orchestration complexity that makes the implementation more brittle.
- Distinctive: line 112
When you identify a code-quality problem, prefer suggestions like:
- Distinctive: line 114
Delete a whole layer of indirection rather than polishing it.
- Distinctive: line 124
Delete wrappers that do not meaningfully clarify the API.
- Distinctive: line 131
Do not be satisfied with "maybe rename this" feedback when the real issue is structural.
- Distinctive: line 132
Do not be satisfied with a merely cleaner version of the same messy idea if there is a plausible path to a much simpler idea.
- Distinctive: line 137
Do not be rude, but do not soften major maintainability issues into mild suggestions.
- Distinctive: line 138
If the code is making the codebase messier, say so clearly.
- Distinctive: line 139
If the implementation missed an opportunity for a dramatic simplification, say that clearly too.
- Distinctive: line 165
Do not flood the review with low-value nits if there are larger structural issues.
- Distinctive: line 166
Prefer a smaller number of high-conviction comments over a long list of cosmetic notes.
- Distinctive: line 170
Do not approve merely because behavior seems correct.
- Distinctive: line 173
no clear structural regression
- Distinctive: line 174
no obvious missed opportunity to make the implementation dramatically simpler when such a path is visible
- Distinctive: line 175
no unjustified file-size explosion
- Distinctive: line 176
no obvious spaghetti-growth from special-case branching
- Distinctive: line 177
no obviously hacky or magical abstraction that makes the code harder to reason about
- Very specific: line 178
no unnecessary wrapper/cast/optionality churn obscuring the real design
- Distinctive: line 179
no clear architecture-boundary leak or avoidable canonical-helper duplication
- Distinctive: line 180
no missed opportunity for an obvious decomposition that would materially improve maintainability
- Distinctive: line 182
Treat these as presumptive blockers / critical findings unless clearly justified:
- Distinctive: line 191
If those conditions are not met, leave explicit, actionable feedback and push for a cleaner decomposition.
“Common” is measured: kept by at least 6 in 10 of the 18 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Code Quality Review
Use this skill for an unusually strict review focused on implementation quality, maintainability, abstraction quality, and codebase health.
Above all, this skill should push the reviewer to be ambitious about code structure. Do not merely identify local cleanup opportunities. Actively search for "code judo" moves: restructurings that preserve behavior while making the implementation dramatically simpler, smaller, more direct, and more elegant.
Core Prompt
Start from this baseline:
Perform a deep code quality audit of the target code or changes ( whether it is a commit, PR or existing codebase snippet ). Rethink how to structure / implement the changes to meaningfully improve code quality without impacting behavior. Work to improve abstractions, modularity, reduce Spaghetti code, improve succinctness and legibility. Be ambitious, if there is a clear path to improving the implementation that involves restructuring some of the codebase, go for it. Be extremely thorough and rigorous. Measure twice, cut once.
Non-Negotiable Additional Standards
Apply the baseline prompt above, plus these explicit review rules:
- Be ambitious about structural simplification.
- Do not stop at "this could be a bit cleaner."
- Look for opportunities to reframe the change so that whole branches, helpers, modes, conditionals, or layers disappear entirely.
- Prefer the solution that makes the code feel inevitable in hindsight.
- Assume there is often a "code judo" move available: a re-organization that uses the existing architecture more effectively and makes the change dramatically simpler and more elegant.
- If you see a path to delete complexity rather than rearrange it, push hard for that path.
- Do not allow a change or existing file to exceed 1k lines without a very strong reason.
- Treat this as a strong code-quality smell by default.
- Prefer extracting helpers, subcomponents, modules, or local abstractions instead of letting a file sprawl past 1000 lines.
- If the diff or existing file crosses that threshold, explicitly ask whether the code should be decomposed first.
- Only waive this if there is a compelling structural reason and the resulting file is still clearly organized.
- Do not allow random spaghetti growth in existing code.
- Be highly suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows.
- If a change adds "weird if statements in random places", treat that as a design problem, not a stylistic nit.
- Prefer pushing the logic into a dedicated abstraction, helper, state machine, policy object, or separate module instead of tangling an existing path.
- Call out changes that make the surrounding code harder to reason about, even if they technically work.
- Bias toward cleaning the design, not just accepting working code.
- If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version.
- Do not rubber-stamp "it works" implementations that leave the codebase messier.
- Strongly prefer simplifications that remove moving pieces altogether over refactors that merely spread the same complexity around.
- Prefer direct, boring, maintainable code over hacky or magical code.
- Treat brittle, ad-hoc, or "magic" behavior as a code-quality problem.
- Be skeptical of generic mechanisms that hide simple data-shape assumptions.
- Flag thin abstractions, identity wrappers, or pass-through helpers that add indirection without buying clarity.
- Push hard on type and boundary cleanliness when they affect maintainability.
- Question unnecessary optionality,
unknown,any, or cast-heavy code when a clearer type boundary could exist. - Prefer explicit typed models or shared contracts over loosely-shaped ad-hoc objects.
- If a branch relies on silent fallback to paper over an unclear invariant, ask whether the boundary should be made explicit instead.
- Question unnecessary optionality,
- Keep logic in the canonical layer and reuse existing helpers.
- Call out feature logic leaking into shared paths or implementation details leaking through APIs.
- Prefer existing canonical utilities/helpers over bespoke one-offs.
- Push code toward the right package, service, or module instead of normalizing architectural drift.
- Treat unnecessary sequential orchestration and non-atomic updates as design smells when the cleaner structure is obvious.
- If independent work is serialized for no good reason, ask whether the flow should run in parallel instead.
- If related updates can leave state half-applied, push for a more atomic structure.
- Do not over-index on micro-optimizations, but do flag avoidable orchestration complexity that makes the implementation more brittle.
Primary Review Questions
For every meaningful change, ask:
- Is there a "code judo" move that would make this dramatically simpler?
- Can this change be reframed so fewer concepts, branches, or helper layers are needed?
- Does this improve or worsen the local architecture?
- Does the code (or diff) introduce branching complexity where a better abstraction should exist?
- Did a previously cohesive module become more coupled, more stateful, or harder to scan?
- Is this logic living in the right file and layer?
- Did this change enlarge a file or component past a healthy size boundary?
- Are there repeated conditionals that signal a missing model or missing helper?
- Is the implementation direct and legible, or does it rely on special cases and incidental control flow?
- Is this abstraction actually earning its keep, or is it just a wrapper?
- Does the code introduce casts, optionality, or ad-hoc object shapes that obscure the real invariant?
- Is this logic living in the canonical layer, or does it leak details across a boundary?
- Is this orchestration more sequential or less atomic than it needs to be?
What to Flag Aggressively
Escalate findings when you see:
- A complicated implementation where a cleaner reframing could delete whole categories of complexity.
- Refactors that move code around but fail to reduce the number of concepts a reader must hold in their head.
- A file crossing 1000 lines (or an already bloated file being edited without decomposition), especially if the code could be split out.
- New conditionals bolted onto unrelated code paths.
- One-off booleans, nullable modes, or flags that complicate existing control flow.
- Feature-specific logic leaking into general-purpose modules.
- Generic "magic" handling that hides simple structure and makes the code harder to reason about.
- Thin wrappers or identity abstractions that add indirection without simplifying anything.
- Unnecessary casts,
any,unknown, or optional params that muddy the real contract. - Copy-pasted logic instead of extracted helpers.
- Narrow edge-case handling implemented in the middle of an already busy function.
- Refactors that technically pass tests but make the code less modular or less readable.
- "Temporary" branching that is likely to become permanent debt.
- Bespoke helpers where the codebase already has a canonical utility for the job.
- Logic added in the wrong layer/package when it should live somewhere more central.
- Sequential async flow where obviously independent work could stay simpler and clearer with parallel execution.
- Partial-update logic that leaves state less atomic than necessary.
Preferred Remedies
When you identify a code-quality problem, prefer suggestions like:
- Delete a whole layer of indirection rather than polishing it.
- Reframe the state model so conditionals disappear instead of getting centralized.
- Change the ownership boundary so the feature becomes a natural extension of an existing abstraction.
- Turn special-case logic into a simpler default flow with fewer exceptions.
- Extract a helper or pure function.
- Split a large file into smaller focused modules.
- Move feature-specific logic behind a dedicated abstraction.
- Replace condition chains with a typed model or explicit dispatcher.
- Separate orchestration from business logic.
- Collapse duplicate branches into a single clearer flow.
- Delete wrappers that do not meaningfully clarify the API.
- Reuse the existing canonical helper instead of introducing a near-duplicate.
- Make type boundaries more explicit so the control flow gets simpler.
- Move the logic to the package/module/layer that already owns the concept.
- Parallelize independent work when that also simplifies the orchestration.
- Restructure related updates into a more atomic flow when partial state would be harder to reason about.
Do not be satisfied with "maybe rename this" feedback when the real issue is structural. Do not be satisfied with a merely cleaner version of the same messy idea if there is a plausible path to a much simpler idea.
Review Tone
Be direct, serious, and demanding about quality. Do not be rude, but do not soften major maintainability issues into mild suggestions. If the code is making the codebase messier, say so clearly. If the implementation missed an opportunity for a dramatic simplification, say that clearly too.
Good phrases:
this pushes the file past 1k lines (or this file is already over 1k lines). can we decompose this first?this adds another special-case branch into an already busy flow. can we move this behind its own abstraction?this works, but it makes the surrounding code more spaghetti. let's keep the behavior and restructure the implementation.this feels like feature logic leaking into a shared path. can we isolate it?this abstraction seems unnecessary. can we just keep the direct flow?why does this need a cast / optional here? can we make the boundary more explicit instead?this looks like a bespoke helper for something we already have elsewhere. can we reuse the canonical one?i think there's a code-judo move here that makes this much simpler. can we reframe this so these branches disappear?this refactor moves complexity around, but doesn't really delete it. is there a way to make the model itself simpler?
Output Expectations
Prioritize findings in this order:
- Structural code-quality regressions
- Missed opportunities for dramatic simplification / code-judo restructuring
- Spaghetti / branching complexity increases
- Boundary / abstraction / type-contract problems that make the code harder to reason about
- File-size and decomposition concerns
- Modularity and abstraction issues
- Legibility and maintainability concerns
Do not flood the review with low-value nits if there are larger structural issues. Prefer a smaller number of high-conviction comments over a long list of cosmetic notes.
Approval Bar
Do not approve merely because behavior seems correct. The bar for approval is:
- no clear structural regression
- no obvious missed opportunity to make the implementation dramatically simpler when such a path is visible
- no unjustified file-size explosion
- no obvious spaghetti-growth from special-case branching
- no obviously hacky or magical abstraction that makes the code harder to reason about
- no unnecessary wrapper/cast/optionality churn obscuring the real design
- no clear architecture-boundary leak or avoidable canonical-helper duplication
- no missed opportunity for an obvious decomposition that would materially improve maintainability
Treat these as presumptive blockers / critical findings unless clearly justified:
- the code preserves a lot of incidental complexity when there is a plausible code-judo move that would delete it
- the changes push a file past 1000 lines (or leave an oversized file un-decomposed)
- the code introduces or maintains ad-hoc branching that makes the flow tangled
- the code solves a local problem by scattering feature checks across shared code
- the code introduces an unnecessary abstraction, wrapper, or cast-heavy contract that makes the design more indirect
- the code duplicates an existing helper or puts logic in the wrong layer when there is a clear canonical home
If those conditions are not met, leave explicit, actionable feedback and push for a cleaner decomposition.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

