review-clean-code
Analyze code quality based on "Clean Code" principles. Identify naming, function size, duplication, over-engineering, and magic number issues with severity ratings and refactoring suggestions. Use when the user requests code quality checks, refactoring advice, Clean Code analysis, code smell detection, or mentions terms like code review, code quality, refactoring check.
- Installs
- 53
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/heyvhuang/ship-faster --skill review-clean-code- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads review-clean-code automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Clean Code Review
Focused on 7 high-impact review dimensions based on "Clean Code" principles.
Review Workflow
Review Progress:
- [ ] 1. Scan codebase: identify files to review
- [ ] 2. Check each dimension (naming, functions, DRY, YAGNI, magic numbers, clarity, conventions)
- [ ] 3. Rate severity (High/Medium/Low) for each issue
- [ ] 4. Generate report sorted by severity
Core Principle: Preserve Functionality
All suggestions target implementation approach only—never suggest changing the code's functionality, output, or behavior.
Check Dimensions
1. Naming Issues (Meaningful Names)
Check for:
- Meaningless names like
data1,temp,result,info,obj - Inconsistent naming for same concepts (
get/fetch/retrievemixed)
// ❌
const d = new Date();
const data1 = fetchUser();
// ✅
const currentDate = new Date();
const userProfile = fetchUser();
2. Function Issues (Small Functions + SRP)
Check for:
- Functions exceeding 100 lines
- More than 3 parameters
- Functions doing multiple things
// ❌ 7 parameters
function processOrder(user, items, address, payment, discount, coupon, notes)
// ✅ Use parameter object
interface OrderParams { user: User; items: Item[]; shipping: Address; payment: Payment }
function processOrder(params: OrderParams)
3. Duplication Issues (DRY)
Check for:
- Similar if-else structures
- Similar data transformation/error handling logic
- Copy-paste traces
4. Over-Engineering (YAGNI)
Check for:
if (config.legacyMode)branches that are never true- Interfaces with only one implementation
- Useless try-catch or if-else
// ❌ YAGNI violation: unused compatibility code
if (config.legacyMode) {
// 100 lines of compatibility code
}
5. Magic Numbers (Avoid Hardcoding)
Check for:
- Bare numbers without explanation
- Hardcoded strings
// ❌
if (retryCount > 3) // What is 3?
setTimeout(fn, 86400000) // How long is this?
// ✅
const MAX_RETRY_COUNT = 3;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;
6. Structural Clarity (Readability First)
Check for:
- Nested ternary operators
- Overly compact one-liners
- Deep conditional nesting (> 3 levels)
// ❌ Nested ternary
const status = a ? (b ? 'x' : 'y') : (c ? 'z' : 'w');
// ✅ Use switch or if/else
function getStatus(a, b, c) {
if (a) return b ? 'x' : 'y';
return c ? 'z' : 'w';
}
7. Project Conventions (Consistency)
Check for:
- Mixed import order (external libs vs internal modules)
- Inconsistent function declaration styles
- Mixed naming conventions (camelCase vs snake_case)
// ❌ Inconsistent style
import { api } from './api'
import axios from 'axios' // External lib should come first
const handle_click = () => { ... } // Mixed naming style
// ✅ Unified style
import axios from 'axios'
import { api } from './api'
function handleClick(): void { ... }
[!TIP] Project conventions should refer to
CLAUDE.md,AGENTS.md, or project-defined coding standards.
Severity Levels
| Level | Criteria |
|---|---|
| High | Affects maintainability/readability, should fix immediately |
| Medium | Room for improvement, recommended fix |
| Low | Code smell, optional optimization |
Output Format
### [Issue Type]: [Brief Description]
- **Principle**: [Clean Code principle]
- **Location**: `file:line`
- **Severity**: High/Medium/Low
- **Issue**: [Specific description]
- **Suggestion**: [Fix direction]
Artifacts (Pipeline Mode)
- Output:
clean-code-review.md(human-readable report) - Output:
clean-code-review.json(structured issue list for aggregation/deduplication/statistics)
References
Detailed examples: See detailed-examples.md
- Complete cases for each dimension (naming, functions, DRY, YAGNI, magic numbers)
Language patterns: See language-patterns.md
- TypeScript/JavaScript common issues
- Python common issues
- Go common issues
Multi-Agent Parallel
Split by the following dimensions for parallel multi-agent execution:
- By check dimension - One agent per dimension (7 total)
- By module/directory - One agent per module
- By language - One agent each for TypeScript, Python, Go
- By file type - Components, hooks, utilities, type definitions
Example: /review-clean-code --scope=components or --dimension=naming
Deduplication and unified severity rating needed when aggregating.
FAQ
What does the review-clean-code skill do?
Analyze code quality based on "Clean Code" principles. Identify naming, function size, duplication, over-engineering, and magic number issues with severity ratings and refactoring suggestions. Use when the user requests code quality checks, refactoring advice, Clean Code analysis, code smell detection, or mentions terms like code review, code quality, refactoring check.
How do I install review-clean-code?
Run npx skills add https://github.com/heyvhuang/ship-faster --skill review-clean-code in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/review-clean-code/ (personal) or .claude/skills/review-clean-code/ (project).
Which AI agents can use review-clean-code?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is review-clean-code safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains review-clean-code?
It is published by heyvhuang in heyvhuang/ship-faster. It has 53 recorded installs.
More from heyvhuang/ship-faster
mcp-stripe
heyvhuang/ship-faster
Stripe MCP transaction operations skill. Execute transaction operations via Stripe MCP server (https://mcp.stripe.com): customer management, products/prices, invoices, payment links, subscriptions, refunds, dispute handling, balance queries. Triggers: user requests Stripe operations including create customer, create product, create invoice, generate payment link, query transactions, process refunds, manage subscriptions, view disputes, check balance, etc.
mcp-supabase
heyvhuang/ship-faster
Execute database operations via Supabase MCP (query/write/migration/logs/type generation). Triggers: query/statistics/export/insert/update/delete/fix/backfill/migrate/logs/alerts/type generation. Does not trigger for: pure architecture discussion or code planning. Write operations require confirmation; UPDATE/DELETE without WHERE is refused.
review-doc-consistency
heyvhuang/ship-faster
Documentation consistency reviewer that checks alignment between code implementation and documentation. Use when user requests reviewing documentation vs code consistency, checking if README/docs are outdated, verifying API documentation accuracy. Applicable for (1) reviewing README vs implementation consistency (2) checking if docs/ directory content is outdated (3) verifying API/config documentation accuracy (4) generating documentation consistency reports. Trigger words include doc review, documentation consistency, check outdated docs, verify docs.
tool-ast-grep-rules
heyvhuang/ship-faster
Write AST-based code search and rewrite rules using ast-grep YAML. Create linting rules, code modernizations, and API migrations with auto-fix. Use when the user mentions ast-grep, tree-sitter patterns, code search rules, lint rules with YAML, AST matching, or code refactoring patterns.
tool-openclaw
heyvhuang/ship-faster
Help users install, configure, operate, and migrate OpenClaw (gateway, channels, nodes, plugins, model/auth setup). Use when answering OpenClaw setup/debug questions or model migration questions; use the local docs snapshot bundled with this skill as the source of truth. Triggers: openclaw, clawdbot, clawd, clawdhub, gateway, onboard, channels login, whatsapp, telegram, discord, mattermost, pairing, nodes, sandboxing, tailscale, provider migration, Claude to GPT, model swap.
tool-ui-ux-pro-max
heyvhuang/ship-faster
Use when you need concrete UI/UX inputs (palette, typography, landing patterns, UX/a11y constraints) to drive design or review. Searchable UI/UX design intelligence (styles, palettes, typography, landing patterns, charts, UX/a11y guidelines + stack best practices) backed by CSV + a Python search script. Triggers: UIUX/uiux, UI/UX, UX design, UI design, design system, design spec, color palette, typography, layout, animation, accessibility/a11y, component styling. Actions: search, recommend, review, improve UI.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.