clean-code
Use when writing, reviewing, or refactoring code for maintainability and readability. Triggers on code reviews, naming discussions, function design, error handling, and test writing. Based on Robert C. Martin's Clean Code handbook with modern corrections.
- Installs
- 844
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/pproenca/dot-skills --skill 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 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.
Robert C. Martin (Uncle Bob) Clean Code Best Practices
Comprehensive software craftsmanship guide based on Robert C. Martin's "Clean Code: A Handbook of Agile Software Craftsmanship", updated with modern corrections where the original 2008 advice has been superseded. Contains 48 rules across 10 categories, prioritized by impact to guide code reviews, refactoring decisions, and new development. Examples are primarily in Java but principles are language-agnostic.
When to Apply
Reference these guidelines when:
- Writing new functions, classes, or modules
- Naming variables, functions, classes, or files
- Reviewing code for maintainability issues
- Refactoring existing code to improve clarity
- Writing or improving unit tests
- Wrapping third-party dependencies
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Meaningful Names | CRITICAL | name- |
| 2 | Functions | CRITICAL | func- |
| 3 | Comments | HIGH | cmt- |
| 4 | Formatting | HIGH | fmt- |
| 5 | Error Handling | HIGH | err- |
| 6 | Objects and Data Structures | MEDIUM-HIGH | obj- |
| 7 | Boundaries | MEDIUM-HIGH | bound- |
| 8 | Classes and Systems | MEDIUM-HIGH | class- |
| 9 | Unit Tests | MEDIUM | test- |
| 10 | Emergence and Simple Design | MEDIUM | emerge- |
Quick Reference
1. Meaningful Names (CRITICAL)
name-intention-revealing- Use names that reveal intentname-avoid-disinformation- Avoid misleading namesname-meaningful-distinctions- Make meaningful distinctionsname-pronounceable- Use pronounceable namesname-searchable- Use searchable namesname-avoid-encodings- Avoid encodings in namesname-class-noun- Use noun phrases for class namesname-method-verb- Use verb phrases for method names
2. Functions (CRITICAL)
func-small- Keep functions smallfunc-one-thing- Functions should do one thingfunc-abstraction-level- Maintain one level of abstractionfunc-minimize-arguments- Minimize function argumentsfunc-no-side-effects- Avoid side effectsfunc-command-query-separation- Separate commands from queriesfunc-dry- Do not repeat yourself
3. Comments (HIGH)
cmt-express-in-code- Express yourself in code, not commentscmt-explain-intent- Use comments to explain intentcmt-avoid-redundant- Avoid redundant commentscmt-avoid-commented-out-code- Delete commented-out codecmt-warning-consequences- Use warning comments for consequences
4. Formatting (HIGH)
fmt-vertical-formatting- Use vertical formatting for readabilityfmt-horizontal-alignment- Avoid horizontal alignmentfmt-team-rules- Follow team formatting rulesfmt-indentation- Respect indentation rules
5. Error Handling (HIGH)
err-use-exceptions- Separate error handling from happy patherr-write-try-catch-first- Write try-catch-finally firsterr-provide-context- Provide context with exceptionserr-define-by-caller-needs- Define exceptions by caller needserr-avoid-null- Avoid returning and passing null
6. Objects and Data Structures (MEDIUM-HIGH)
obj-data-abstraction- Hide data behind abstractionsobj-data-object-asymmetry- Understand data/object anti-symmetryobj-law-of-demeter- Follow the Law of Demeterobj-avoid-hybrids- Avoid hybrid data-object structuresobj-dto- Use DTOs for data transfer
7. Boundaries (MEDIUM-HIGH)
bound-wrap-third-party- Wrap third-party APIsbound-learning-tests- Write learning tests for third-party code
8. Classes and Systems (MEDIUM-HIGH)
class-small- Keep classes smallclass-cohesion- Maintain class cohesionclass-organize-for-change- Organize classes for changeclass-isolate-from-change- Isolate classes from changeclass-separate-concerns- Separate construction from use
9. Unit Tests (MEDIUM)
test-first-law- Follow the three laws of TDDtest-keep-clean- Keep tests cleantest-one-assert- One concept per testtest-first-principles- Follow FIRST principlestest-build-operate-check- Use Build-Operate-Check pattern
10. Emergence and Simple Design (MEDIUM)
emerge-simple-design- Follow the four rules of simple designemerge-expressiveness- Maximize expressiveness
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
Reference Files
| File | Description |
|---|---|
| references/_sections.md | Category definitions and ordering |
| assets/templates/_template.md | Template for new rules |
| metadata.json | Version and reference information |
FAQ
What does the clean-code skill do?
Use when writing, reviewing, or refactoring code for maintainability and readability. Triggers on code reviews, naming discussions, function design, error handling, and test writing. Based on Robert C. Martin's Clean Code handbook with modern corrections.
How do I install clean-code?
Run npx skills add https://github.com/pproenca/dot-skills --skill 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/clean-code/ (personal) or .claude/skills/clean-code/ (project).
Which AI agents can use 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 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 clean-code?
It is published by pproenca in pproenca/dot-skills. It has 844 recorded installs.
More from pproenca/dot-skills
zod
pproenca/dot-skills
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
vitest
pproenca/dot-skills
Vitest testing framework patterns for test setup, async testing, mocking with vi., snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
react-hook-form
pproenca/dot-skills
React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, useFieldArray, the subscribe() API, and the Watch / FormStateSubscribe / FieldArray render-prop components. Covers RHF 7.82 additions including resetDefaultValues() and the disabled field-array option. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).
emilkowal-animations
pproenca/dot-skills
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
nuqs
pproenca/dot-skills
nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
clean-architecture
pproenca/dot-skills
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
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.