Index of every page on this site: llms.txt
All skills
nielsmadan avatar

/review-cleancode

@9fbe49f
Run it yourself

Review code for clean-code principles — SOLID, DRY, YAGNI, KISS, code smells. Triggers "review clean code", "check DRY/SOLID", "code smells".

Use this Skill: https://skilld.dev/gh/nielsmadan/agentic-coding/review-cleancode

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈40 tokens for metadata: the name and description. ≈3.1k when used: this file. ≈3.6k more on demand in 1 file.

Description uses 2.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈160 characters, or 2.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Review Clean Code

Language-agnostic clean code review covering SOLID, DRY, YAGNI, KISS, design principles, and code smells.

Review grading

Use only these finding priorities, in descending order:

  • Critical Issues (Must Fix): a verified path causes data loss, a security failure, a materially wrong operation, or makes a core workflow unusable without reasonable recovery.
  • Improvements (Should Fix): an ordinary supported workflow demonstrably fails or repeatedly imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.
  • Suggestions (Nice to Have): a worthwhile improvement with small practical impact, including optional polish, local simplification, and rare recoverable edge cases.

Grade the demonstrated consequence, realistic reachability, and available recovery against project priorities. A category, missing convention, hypothetical future problem, or confidence that a claim is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep unverified claims in validation gaps, outside the graded finding count; distinguish suggestions from defects. For plans, trace the consequence if implemented and state the assumptions.

Use the short labels Must Fix, Should Fix, and Nice to Have in summaries and ledgers. Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings separate. When called by code-review, return its requested evidence and impact fields; the parent owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.

Usage

/review-cleancode                  # Review context-related code
/review-cleancode --staged         # Review staged changes
/review-cleancode --unpushed       # Review files changed across all unpushed commits
/review-cleancode --changed        # Review unstaged changes
/review-cleancode --all            # Full codebase audit (parallel agents)
/review-cleancode --multi          # Also get external advisor opinions

Scope

Flag Scope Method
(none) Context-related code Files from the current conversation context. If no context, ask the user to specify files or use --staged/--changed/--all.
--staged Staged changes git diff --cached --name-only
--unpushed Files changed across unpushed commits git diff --name-only $(git rev-list HEAD --not --remotes | tail -1)^..HEAD
--changed Unstaged changes git diff --name-only
--all Full codebase Glob source files, parallel agents
--multi Add external opinions Combines with any scope above; invokes second-opinion --quick

--unpushed derives its range from git rev-list HEAD --not --remotes (oldest unpushed commit's parent → HEAD). If nothing is unpushed, or there is no remote/upstream (or the range walks back to the root commit) so it can't be determined reliably, stop and ask the user to pick another scope. Like --staged, it reviews full file content, not just the diff.

Gotchas

  • Default scope (no flag) uses conversation context, which may be stale if context has shifted during the session.
  • DRY violations across distant files are hard to detect without --all scope. Staged reviews only catch duplication within the diff.
  • YAGNI is subjective — unused flexibility may be intentional (library/framework code). Check if the code is consumed externally before flagging.

Workflow

  1. Determine scope based on flags (see Scope table above)

  2. Read CLAUDE.md in the repository root to understand project-specific conventions

  3. Review each file against all 5 categories in the Clean Code Checklist below

  4. Parallelize if scope has >5 files: spawn one sub-agent per category, each scanning all files for that category. Merge results and deduplicate.

    Dispatch workers that return findings without editing files. Disable delegation tools where supported; read-only access alone does not prevent delegation. Any coordinating role needs explicit subtasks, a descendant limit, and a stopping condition in its brief.

  5. External opinions (if --multi): invoke second-opinion --quick, which queries every advisor it has configured, in parallel (the roster lives in the second-opinion skill), with this prompt:

Read-only clean code review. Review the code in this repository (use `git diff --cached` for `--staged`, `git diff` for `--changed`, or read the relevant files). Evaluate against clean code principles: SOLID, DRY, YAGNI, KISS, Law of Demeter, code smells (god classes, long methods, feature envy, primitive obsession, shotgun surgery). Provide a focused review in 300 words or less.

Wait for all external results before proceeding to step 6.

  1. Classify severity using Review grading; justify the impact with evidence.
  2. Report findings grouped by severity using the Output Format below

Clean Code Checklist

1. SOLID Principles

  • SRP: Does the class/function have a single reason to change? Can you describe it without "and"?
  • OCP: Can new behavior be added without modifying existing code? Watch for growing switch/if chains on type codes.
  • LSP: Do subclasses honor the parent's contract? Watch for overrides that throw "not implemented" or change semantics.
  • ISP: Are interfaces focused? Do implementors need to stub unused methods?
  • DIP: Do high-level modules depend on abstractions or concrete implementations?

2. Foundational Principles

  • DRY: Is the same logic repeated in multiple places? Would a change require edits in multiple files?
  • YAGNI: Is there code, parameters, or abstraction for hypothetical future needs that nothing currently uses?
  • Reuse-first (anti-reinvention): Before accepting hand-written code, walk the ladder — could it be replaced by (1) a helper/util/pattern already in this codebase, (2) the standard library, (3) a native platform feature (<input type="date"> over a date-picker lib, CSS over JS, a DB constraint over app code), or (4) an already-installed dependency? Hand-rolling what one of these already ships is the most common avoidable bloat; a new dependency added for what a few lines or a present dep covers is its inverse. When flagging, name the specific replacement, not just "this is complex."
  • KISS: Could a simpler approach achieve the same result? Are there clever tricks that obscure intent?
  • Validation clarity: Repeated checks, redundant guards, and parallel case lists that could share one contract or representation. Do not demand checks already guaranteed by callers. Cross-module placement belongs to architecture; measurable wasted work belongs to performance; contradictory validation, silently skipped work, or validation after irreversible effects belongs to review-correctness.

3. Design Principles

  • Law of Demeter: Long chains like a.getB().getC().getValue()?
  • Separation of Concerns: Business logic mixed with infrastructure, UI, or persistence?
  • Composition over Inheritance: Deep hierarchies (>2 levels) used for code reuse rather than polymorphism?
  • Principle of Least Astonishment: Does the function do what its name suggests? Hidden side effects?
  • Tell Don't Ask: Querying object state then acting on it externally instead of telling the object?
  • Command-Query Separation: Methods that both mutate state and return data?
  • Encapsulation: Internal state exposed directly? Getters returning mutable references?
  • Cohesion/Coupling: Unrelated methods in one class? Excessive dependencies between modules?

4. Code Smells

  • God Class: Class with too many responsibilities (>~300 lines, multiple unrelated method groups)
  • Long Method: Method doing multiple phases (>~20 lines, multiple levels of nesting)
  • Feature Envy: Method uses another class's data more than its own
  • Data Class: Fields + getters/setters only, no behavior
  • Duplicate Code: Identical or near-identical blocks in multiple locations
  • Message Chains: Long chains through intermediate objects
  • Primitive Obsession: Strings/ints for concepts that deserve value types
  • Long Parameter List: 4+ parameters that should be grouped
  • Dead Code: Unused functions, unreachable branches, unused imports
  • Speculative Generality: Abstractions, configs, or flexibility for nonexistent use cases
  • Shotgun Surgery: One logical change requires edits across many files
  • Divergent Change: One class modified for multiple unrelated reasons
  • Data Clumps: Same group of parameters passed together repeatedly

5. Readability & Structure

  • Guard Clauses: Deep nesting that could use early returns
  • Meaningful Names: Cryptic abbreviations, generic names (data, info, process)
  • Small Functions: Functions with section comments (signal they do too much)
  • Comments: "What" comments that should be "why" comments, or could be replaced by better naming
  • Declarative Style: Imperative loops where filter/map/reduce would be clearer (but not dogmatically)

For annotated BAD/GOOD code examples for each category, see references/cleancode-checklist.md.

Output Format

## Clean Code Review: {scope}

### Critical Issues (Must Fix)
- {file}:{line} - {category}: {description}
  **Impact:** {why it matters}
  **Fix:** {solution with code example}

### Improvements (Should Fix)
- {file}:{line} - {category}: {description}
  **Fix:** {solution}

### Suggestions (Nice to Have)
- {file} - {category}: {description}

**Net:** ~{N} lines removable across the findings above (omit if nothing is cuttable).

If --multi was used, append:

### External Opinions

Add one subsection per advisor that responded, titled with the advisor's name as reported by `second-opinion`:

#### {advisor name}
{that advisor's review}

#### Cross-Model Agreement
{areas where the external advisors agree/disagree with the Claude review — consensus issues (flagged by multiple models) get higher confidence}

Examples

Staged changes with DRY violation:

/review-cleancode --staged

Reviews staged files and catches the same email validation logic duplicated in createUser and updateUser. Reports Nice to Have if this is only local duplication; Should Fix requires evidence that the copies drift or create meaningful maintenance cost. Suggests a shared validateEmail function.

Full codebase audit finds god class:

/review-cleancode --all

Parallel agents scan by category. Finds AppService handling auth, payments, notifications, and reporting — four distinct responsibilities. Reports Should Fix if the mixed responsibilities cause meaningful change coupling, with a split plan. The number of responsibilities alone does not establish a finding.

Get external opinions on clean code quality:

/review-cleancode --multi --staged

Runs the 5-category review plus the external advisors. Cross-model agreement highlights a SOLID violation multiple reviewers independently flagged.

Troubleshooting

Too many false positives on YAGNI

Solution: Check whether the code is a library or framework consumed by external callers. Flexibility is expected in public APIs. Add context in a code comment (e.g., // Public API: consumers use these options) and re-run.

DRY violations not caught across distant files

Solution: Use --all scope. The default, --staged, and --changed scopes only see a subset of the codebase, so cross-file duplication requires the full scan.

Disagreement on class/method size thresholds

Solution: The ~300 line / ~20 line guidelines are heuristics, not rules. A 25-line method that does one clear thing is fine. The real signal: can you describe what it does in one sentence without "and"?

Notes

  • Apply judgment, not dogma — these are principles, not laws
  • Consider context: a startup prototype has different standards than a banking system
  • Language idioms matter: what's idiomatic in Python may not apply in Go
  • For --all, use parallel agents per category (5 agents)
  • Multiple violations compound: a god class with long methods and feature envy is worse than the sum of its parts

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts7mo3 checks · Risk SAFE
  • Gen Agent Trust Hub7mo

    The skill reviews repository code for clean code principles. It is designed to send code snippets to external large language model providers for analysis and is vulnerable to indirect prompt injection if malicious instructions are present in the files being reviewed.

  • Socket7mo

    No alerts

  • Snyk7mo

    Risk: LOW · No issues

Signed by skilld at 9fbe49f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 2 weeks ago
argument-hint
[--staged | --unpushed | --changed | --all | --multi]
effort
high

README badge

README badge for nielsmadan/agentic-coding/review-cleancode