clean-code skill
✓ VerifiedProvides grounded advice and justifications based on Robert C. Martin's Clean Code principles for code reviews, refactoring, and TDD.
- GitHub stars
- 11
- Files
- 23
- Last commit
- Oct 10, 2026
- License
- MIT
- Allowed tools
- —
What does the clean-code skill do?
clean-code provides grounded advice and justifications based on Robert C. Martin's Clean Code principles for code reviews, refactoring, and TDD.
Summary generated from the skill's SKILL.md.
About the clean-code skill
Applying Robert C. Martin's principles to code reviews and refactoring is what this skill enables for software developers and engineers. It acts as a synthesized study aid that provides grounded advice and justifications based on the Clean Code handbook. Instead of acting as a linter or a tool that automatically fixes code, it serves as a knowledge base to explain why specific patterns constitute code smells and how to address them using established frameworks.
When an agent is tasked with a live code review or a cleanup, it loads specific reference files such as the decision cheat sheet or individual chapter files to provide citations. It relies on a routing table to pinpoint exact heuristics, such as SRP or TDD principles, and can translate Java-centric examples into other languages using a cross-language map. This ensures that every piece of advice is backed by a specific chapter or heuristic ID, providing a clear taxonomy for professional software craftsmanship.
What an agent can do with it
- 1Justify code review findingsExplain why a specific piece of code is considered a smell and provide the correct fix.
- 2Study software craftsmanship principlesAsk specific questions about what the author says regarding various programming topics.
- 3Translate principles to new languagesAdapt Clean Code concepts from Java to a different programming language.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the clean-code skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the clean-code skill in Claude Code
~/.claude/skills/clean-code/SKILL.md
$ npx degit renky1025/agent-skills/clean-code ~/.claude/skills/clean-codeInstall the clean-code skill in Claude Code (project)
.claude/skills/clean-code/SKILL.md
$ npx degit renky1025/agent-skills/clean-code .claude/skills/clean-codeInstall the clean-code skill in Codex
~/.agents/skills/clean-code/SKILL.md
$ npx degit renky1025/agent-skills/clean-code ~/.agents/skills/clean-codeInstall the clean-code skill in Gemini CLI
~/.gemini/skills/clean-code/SKILL.md
$ npx degit renky1025/agent-skills/clean-code ~/.gemini/skills/clean-codeInstall the clean-code skill in Claude.ai
npx degit renky1025/agent-skills/clean-code clean-code && zip -r clean-code.zip clean-code # claude.ai → Customize → Skills → + → Create skill → Upload a skill → clean-code.zip
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablerenky1025/agent-skills/clean-code is public and reachablegithub.com/renky1025/agent-skills/tree/HEAD/clean-code ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-10github.com/renky1025/agent-skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/renky1025/agent-skills/blob/HEAD/clean-code/SKILL ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/renky1025/agent-skills/blob/HEAD/clean-code/SKILL ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 150 linesgithub.com/renky1025/agent-skills/blob/HEAD/clean-code/SKILL ↗Pass
SKILL.md
View on GitHubClean Code
Author: Robert C. Martin (Uncle Bob) | Pages: ~462 | Chapters: 17 | Generated: 2026-08-24
Purpose
A synthesised study aid for Clean Code: it maps every named framework, principle, anti-pattern, and heuristic in the book to a reference file, then routes a question or a review finding to the file that answers it. It produces grounded advice with chapter citations — not the book text, and not a linting tool.
When to Use
- Naming, functions, comments, formatting, objects vs data structures, error handling, boundaries, tests/TDD, classes/SRP, systems, concurrency, refactoring, code smells.
- A live review or cleanup where you must name why something is a smell and what to do.
- Studying the book, or asking "what does Uncle Bob say about X".
- Trigger phrases: 整洁代码, 重构, 代码质量, 命名, 函数设计, 注释, 代码味道, 反模式, 测试驱动; clean code, naming, TDD, error handling, code smell, code review, SRP.
When NOT to Use
- Review-and-fix of a diff ->
claude-simplifyruns the review and applies fixes; this skill only supplies the justification the review cites. - Beyond the book — design patterns, architecture, framework idioms -> say it is out of scope; do not extrapolate book positions.
- Untrusted third-party code safety ->
skill-security-check. - Language tooling (linters, formatters, rule configs) -> not covered.
Workflow
A. Look something up
- Classify the question into a topic in the Decision Rules table.
- Read that one file; preloading
references/defeats the routing table. - Follow a chapter's cross-reference only when the question actually needs it.
- Answer from the loaded content, citing chapter and heuristic ids (
Ch 3,G5,F1). - For a non-Java language, read
references/appendix-lang-map.mdand translate rather than quoting Java syntax.
B. Apply the book to a live code review
- Read
references/cheatsheet.md— it is the review lens. - Tag each diff finding with its C/E/F/G/J/N/T heuristic id; load
references/chapters/ch17-smells-and-heuristics.mdfor tags absent from the cheat sheet. - Name the fixing framework, then load the chapter that owns it via the routing table.
- Load
references/patterns.mdwhen the fix is a technique and you need its trade-offs. - Report each finding as: id -> why -> fix -> citation.
Decision Rules
Route by topic; load exactly one row's file:
| Topic | File | Topic | File |
|---|---|---|---|
| Boy Scout Rule, LeBlanc's law, professionalism | references/chapters/ch01-clean-code.md |
Classes, SRP, cohesion | references/chapters/ch10-classes.md |
| Naming: intent-revealing, no encodings | references/chapters/ch02-meaningful-names.md |
Systems: construction vs use, DI, factory | references/chapters/ch11-systems.md |
| Functions: Do One Thing, step-down, CQS, args | references/chapters/ch03-functions.md |
Four Rules of Simple Design, emergence | references/chapters/ch12-emergence.md |
| Comments: good vs bad | references/chapters/ch04-comments.md |
Concurrency: isolation, shared state | references/chapters/ch13-concurrency.md |
| Formatting: newspaper metaphor, ordering | references/chapters/ch05-formatting.md |
Args case study, festering pile, refinement | references/chapters/ch14-successive-refinement.md |
| Objects vs data, Law of Demeter | references/chapters/ch06-objects-and-data-structures.md |
Extract Method, Collecting Parameter | references/chapters/ch15-junit-internals.md |
| Errors, null, Special Case | references/chapters/ch07-error-handling.md |
enum over int, Feature Envy fix, factory | references/chapters/ch16-refactoring-serialdate.md |
| Boundaries, learning tests, adapters | references/chapters/ch08-boundaries.md |
Smells (C/E/F/G/J/N/T), DRY, ONE SWITCH | references/chapters/ch17-smells-and-heuristics.md |
| TDD three laws, F.I.R.S.T., BUILD-OPERATE-CHECK | references/chapters/ch09-unit-tests.md |
Cross-chapter topics: Demeter / Feature Envy -> ch06 + ch17; DRY -> ch12 + ch17; refactoring -> ch14 + ch16; Boy Scout Rule -> ch01 + ch15.
Other routing:
- One-line definition only ->
references/core-frameworks.md; escalate to the chapter after. - Concrete technique or pattern + trade-offs ->
references/patterns.md. - A term you cannot place ->
references/glossary.md, which names its chapter. - A "what should I decide" question ->
references/cheatsheet.md. - Conflict between two answers -> apply Priority below.
Constraints
- Never present this skill as the book's verbatim text. It is a study aid; attribute paraphrases as "the book's argument", never as a quotation.
- Cite chapter and heuristic ids whenever you assert a principle.
- Do not summarise detail away. One-liners orient only; when reasoning or edge cases matter, read the chapter and answer from it.
- Principles are language-agnostic. Java examples are carriers, not the rule.
- Stay in scope. Outside Clean Code, say so instead of inventing book positions.
Priority
When rules compete:
- Pass all tests before any other design improvement — Simple Design rule 1 (Ch 12).
- Then, in the book's order: remove duplication, polish expressiveness, minimise the number of classes/methods (Ch 12).
- Project conventions and language idioms override the Java-specific J-series heuristics.
- Name the smell before proposing the fix — an unnamed finding cannot be checked.
Stop Conditions
- Stop once the routed file answers the question; never read all 17 chapters.
- Do not chase a framework past the one linked chapter unless the user wants the derivation.
- Topic outside the book -> stop and say so.
Verification
- The answer cites at least one chapter or heuristic id.
- Only the routed file(s) were loaded, not the whole
references/directory. - Non-Java requests were translated via
references/appendix-lang-map.md. - Nothing is presented as a verbatim book quotation.
- Review findings are reported as id -> why -> fix -> citation.
Output
- Outcome: Clean Code guidance with chapter citations, or a coded review of a diff.
- Done when: the question is classified, the routed reference was read, and the answer cites its source.
- Evidence: the framework or smell id, its chapter, and the concrete change to make.
References
Load only when needed:
references/core-frameworks.md— read for a one-line definition before escalating.references/cheatsheet.md— read first for any live review or "what should I decide" case.references/glossary.md— read when a term is unfamiliar; it gives the owning chapter.references/patterns.md— read when the fix needs a technique and its trade-offs.references/appendix-lang-map.md— read before quoting Java syntax to a non-Java user.references/chapters/— read only the single chapter named by the routing table.
Related Skills
claude-simplify— runs a diff review and fixes findings; pair with this skill for the taxonomy behind each finding.skill-security-check— pre-install safety review, a different concern.
Files in this skill
23clean-code skill questions
How do I install the clean-code skill in Claude Code?
Run npx degit renky1025/agent-skills/clean-code ~/.claude/skills/clean-code. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the clean-code skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Can this skill automatically fix my code?
No, this skill only provides the justification and reasoning for code smells; you should use claude-simplify to run reviews and apply fixes.
Does it provide verbatim text from the book?
No, it is a synthesized study aid that provides grounded advice with chapter citations rather than quoting the book text directly.
How does it handle non-Java programming languages?
It uses a language map to translate principles and avoid quoting Java-specific syntax for other languages.