Skip to content
Skills Library
Programming · Review & audit

clean-code

/clean-code

This skill should be used when the user asks to "refactor code", "review code quality", "apply clean code principles", "check for code smells", "improve code design", "do a clean code review", "apply SOLID principles", "fix naming", "reduce complexity", or when performing the refactor phase of a TDD cycle.

Author
t1 ↗
Repository
tdder ↗
Licence
Apache-2.0
Last repository change
09.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.08.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

This skill should be used when the user asks to "refactor code", "review code quality", "apply clean code principles", "check for code smells", "improve code design", "do a clean code review", "apply SOLID principles", "fix naming", "reduce complexity", or when performing the refactor phase of a TDD cycle.

Triggers from the description

refactor codereview code qualityapply clean code principlescheck for code smellsimprove code designdo a clean code reviewapply SOLID principlesfix naming
Original author description

This skill should be used when the user asks to "refactor code", "review code quality", "apply clean code principles", "check for code smells", "improve code design", "do a clean code review", "apply SOLID principles", "fix naming", "reduce complexity", or when performing the refactor phase of a TDD cycle.

How it works

  1. Philosophy
  2. Core Principles (Always Apply)
  3. Refactoring Scope
  4. Refactoring Priority Order
  5. Refactoring Patterns
  6. Exception Handling
  7. Design for Testability
  8. Test Code Quality
  9. Quick Reference Checklist
Original SKILL.md headings · 172 lines, 1,021 words
SKILL.md preview
---
name: clean-code
description: >
  This skill should be used when the user asks to "refactor code", "review code quality",
  "apply clean code principles", "check for code smells", "improve code design",
  "do a clean code review", "apply SOLID principles", "fix naming", "reduce complexity",
  or when performing the refactor phase of a TDD cycle.
---

# Clean Code Principles

Disciplined development approach for writing high-quality, maintainable code.
This skill is language-agnostic; language-specific conventions come from separate skills.

## Philosophy

- **Investment in Low Cost of Change**: Clean code enables continuous modification without exponential complexity growth
- **Boy Scout Rule**: Always leave code cleaner than you found it
- **Simplicity (KISS)**: Always prefer the simpler solution
- **Root Cause Analysis**: Fix problems at their source, not symptoms

## Core Principles (Always Apply)

### 1. Loose Coupling

Components know little about each other. Dependencies flow through well-defined APIs.
Changes in one component minimally affect others. Prefer composition over inheritance.
Depend on abstractions, not concretions.

### 2. High Cohesion

Elements that belong together stay together. Each module has a single, well-defined purpose.
Related functionality is grouped. Unrelated functionality is separated.

### 3. Change is Local

Modifications are contained within boundaries. A feature change affects minimal files/modules.
Stable interfaces protect implementations.

### 4. It is Easy to Remove

Delete dead code immediately. Remove unused abstractions. Eliminate unnecessary features.
Code should be easy to delete, not just easy to add.

### 5. Mind-sized Components

Functions: one screen or less. Classes: under 100 lines as a guideline.
If it cannot be held in working memory, it is too big.

## Refactoring Scope

When multiple code smells or improvements are found, present them as a prioritized markdown list,
then use `AskUserQuestion` to let the user decide how to proceed:

- **Question:** "How do you want to handle these findings?"
- **Options:**
  - "Fix all" — apply all suggestions in priority order
  - "Discuss one by one" — walk through each finding for individual approval

This avoids surprise refactorings and lets the user control scope. This process applies regardless
of whether findings come from direct review or from the `clean-code-reviewer` agent.

When re-evaluating subagent findings, give due weight to the principle the subagent applied.
"It's short enough" or "extraction adds indirection" are not rebuttals — they're rationalizations
unless you name the specific principle that outweighs the one being violated. The bias should be
toward applying the principle, not toward leaving code as-is.

## Refactoring Priority Order

When reviewing or refactoring code, follow this priority order:

### Priority 1: Naming (CRITICAL)

- Evaluate all names for descriptiveness and intent
- Check abstraction level of names
- Rename if purpose has evolved, e.g., through new tests
- Ensure names reveal side effects if any exist
- No encodings or prefixes (no Hungarian notation, no `I` prefix for interfaces)
- Long names for long scopes, short names for short scopes
- **Name helpers by what they do, not what they omit** — e.g. `repositoryWithLocalTempDir()` (describes the
  distinguishing characteristic) instead of `repositoryWithDefaults()` (vague, describes absence of configuration)

### Priority 2: Code Smells Detection

- Duplication (DRY principle)
- Long methods (>20 lines is suspicious)
- Inline comments grouping lines (each group is a method waiting to be extracted)
- Complex conditionals (can they be encapsulated?)
- Feature envy (methods using other classes more than their own)
- Primitive obsession (should primitives be objects?)
- Magic numbers/strings (extract to constants)
- Data clumps (same group of data appearing together)

### Priority 3: SOLID Principles

- **SRP**: Does each class have one reason to change?
- **OCP**: Can behavior be extended without modifying existing code?
- **LSP**: Are subtypes properly substitutable?
- **DIP**: Do high-level modules depend on abstractions?
- **ISP**: Are interfaces client-specific (no "fat" interfaces)?

### Priority 4: Method Design

- One thing per method at one level of abstraction — "short" is not "clean";
  a method that does four short things is still doing four things
- Argument count: 0-2 ideal, 3+ needs refactoring
- No flag/boolean arguments (split into separate methods)
- No output arguments (change object state instead)
- Command-Query Separation (do OR know, not both)
- Methods should be small (5-20 lines guideline)
- Order by flow: public method first, helpers follow in call order

### Priority 5: Structure

- Loose coupling, high cohesion, local change
- Remove dead code (unused methods, commented code)
- Check dependencies (no cycles, proper direction)
- Ensure mind-sized components

## Refactoring Patterns

### Reconcile Differences

When duplication with slight variations is found, extract the variation into parameters
and unify the common structure.

### Isolate Change

Wrap unstable or external dependencies. Create abstractions around things that might change.
Only do this if it also simplifies the code.

### Small Refactorings with Working Code In-Between

Never break tests during refactoring. Make tiny changes, run tests.
If tests fail, undo and take smaller steps.

### Extract Inner Class — Check Visibility First

Before suggesting extraction of an inner class to a top-level class, verify:
1. Is the inner class used outside the enclosing class? If not, it can be `private`.
2. Making a `private` inner class top-level *increases* its visibility to package-private.
3. Prefer tightening visibility (`private`) over extracting, unless the class is already
   used by other classes or extraction enables meaningful independent testing.

File length alone is not sufficient justification for extraction when it widens visibility.

### Encapsulate Conditionals

Extract complex conditions into well-named methods.
Example: `if (timer.hasExpired() && !timer.isRecurrent())` becomes `if (shouldBeDeleted(timer))`

## Exception Handling

- Catch the most specific exception possible
- Catch only where a meaningful reaction is possible or important context can be added
- Use exceptions, not return codes or null (consider Result Object for business states)
- Fail fast: detect and report errors early
- Never swallow exceptions

## Design for Testability

- Constructors should be simple (assign dependencies, do not construct them)
- Dependencies must live as long or longer than the dependent
- Wrap external dependencies (file systems, databases, networks)
- Use test doubles effectively (fakes, mocks, stubs)

## Test Code Quality

- Test code is production code: apply the same quality standards
- One test checks one feature (multiple assertions for same feature are fine)
- Build test domain specific language (builders, fluent APIs, custom assertions)
- FIRST properties: Fast, Isolated, Repeatable, Self-Validating, Timely

## Quick Reference Checklist

For a complete refactoring checklist, consult:

- **`checklist.md`** - Read this checklist to verify all clean code principles have been applied during
  refactoring
Files in this package (2)
  • SKILL.md 7 KB
  • checklist.md 2 KB

Versions

RepositoryScoreLicence
This page · t1/tdder100Apache-2.0
hanspeterdietiker/open-agent-skills100MIT
FrancoStino/opencode-skills-collection100MIT
rootcastleco/rei-skills100MIT
iWiiCK/iwiick-ai-agent-plugin100MIT
sickn33/agentic-awesome-skills100MIT
sagargupta16/claude-skills100MIT
claude-dev-suite/claude-dev-suite100MIT
jonax1337/clean-code-skill100MIT

Database snapshot: 13.11.2026 · package version ef6f8857b642 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90clean-coder
    Enforces Clean Code standards, identifies code smells, and ensures SOLID principles. Use when: clean code, code smell, SOLID, refactor, quality check.
  • 100clean-code-principles
    SOLID principles, design patterns, DRY, KISS, and clean code fundamentals. Use when reviewing architecture, checking code quality, refactoring, or discussing design decisions. Triggers on "review architecture", "check code quality", "SOLID principles", "design patterns", or "clean code".
  • 100code-refactoring-refactor-clean
    Refactor code with clean code principles, SOLID design patterns, and modern software engineering practices to improve quality, maintainability, and performance. Use when cleaning up or restructuring existing code.
  • 95quality-common
    Universal code quality principles applicable to all languages. Covers Clean Code, SOLID, complexity metrics, and quality standards. USE WHEN: user mentions "clean code", "SOLID", "code smells", "refactoring", "complexity", asks about "cyclomatic complexity", "cognitive…
  • 100codebase-cleanup-refactor-clean
    Refactor code with clean code principles, SOLID design patterns, and modern software engineering practices to improve quality, maintainability, and performance. Use when cleaning up or restructuring existing code.
  • 100refactor
    Analyze complexity and smells, draft a safe refactor plan, and execute step-by-step with tests. Use when refactoring code or invoking /refactor.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.