Skip to main content
skill CX Codex

clean-code · mindrally — Claude Code skill: what it does, how to install

The clean-code Claude Code skill guides code writing and review, with an emphasis on clarity and restrained abstractions. It applies to new code, refactors, and quality checks.

Apache-2.0 182 installs ★ 312 updated 2026-10-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Mindrally/skills --skill clean-code -a claude-code
Open on GitHub

What clean-code does

The skill sets out practices for writing and reviewing code: choose names that show intent, keep functions focused, and limit edits to the requested scope. It also gives a rule for deciding when repeated logic should become a shared function rather than an abstraction added in anticipation.

Its guidance covers tests for changed behavior and edge cases, comments, file structure, and a final check that unrelated code was left alone. The Rule of Three says to wait until a pattern appears a third time before extracting an abstraction. It also cautions against adding dependencies or handling states that the surrounding code makes impossible.

What it helps with

  • choose names that make a variable or function's purpose clear
  • keep a refactor within the requested scope
  • decide when repeated logic should become a shared abstraction
  • check tests and edge cases for a code change

Example prompts for the agent

  • Write a clear function that checks whether a cart can be checked out.
  • Review these changes for unnecessary abstractions and edits outside the request.
  • Fix the bug and add tests for the changed behavior and edge cases.

How to install clean-code

1Skills CLI (Vercel)

npx skills add Mindrally/skills --skill clean-code -a claude-code

2Manually: put the files in place

~/.claude/skills/clean-code/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/clean-code/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about clean-code

How do I install clean-code in Claude Code?

Run npx skills add Mindrally/skills --skill clean-code -a claude-code. The skill file is available at ~/.claude/skills/clean-code/SKILL.md.

What does clean-code do?

It guides code writing and review with practices for clear naming, focused functions, and changes limited to the requested work.

When does clean-code recommend extracting repeated logic?

Its Rule of Three calls for waiting until a pattern appears a third time before creating an abstraction. The first two instances stay separate.

Source text

SKILL.md · Apache-2.0
---
name: clean-code
description: "Clean, maintainable, human-readable code principles combined with anti-over-engineering discipline: naming, single responsibility, DRY, and scoping changes to exactly what was requested. Use when writing new code, refactoring existing code, reviewing code for quality, or deciding how much abstraction a change actually needs."
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# Clean Code

This skill covers writing code that is easy to read and change, and — just as important — avoiding the over-engineering that makes code harder to read and change in the name of "best practices." Both halves matter together: clean code is simple code, not merely well-decorated code.

## Workflow for Writing or Reviewing Code

1. **Scope the change** — Identify exactly what was asked for. Note what's out of scope before writing anything.
2. **Reach for the simplest solution first** — Prefer the direct, obvious implementation over a general or configurable one, unless a concrete current need justifies more.
3. **Name things for their purpose** — Choose names that reveal intent before writing the body of a function or the shape of a type.
4. **Keep functions single-purpose** — If a function needs a comment to explain what it does, split it.
5. **Remove duplication deliberately** — Extract shared logic only once it's actually duplicated (see Rule of Three below), not preemptively.
6. **Write or update tests** — Cover the new behavior and the edge cases it introduces.
7. **Verify scope before delivery** — Confirm only the requested code changed, check for a simpler approach you might have missed, and confirm no unrequested files were touched.

## Meaningful Names

- Variables, functions, and classes should reveal their purpose from the name alone.
- Names should explain why something exists and how it's used, not just its type or contents (`activeUserIds`, not `list1`).
- Avoid abbreviations unless they're universally understood in the domain (`id`, `url` — fine; `usrCfgTmp` — not fine).

## Constants Over Magic Numbers

- Replace hard-coded values with named constants (`MAX_RETRY_COUNT = 3`, not a bare `3` three call sites later).
- Use descriptive constant names that explain the value's purpose, not just its value.
- Keep constants at the top of the file or in a dedicated constants module when shared across files.

## Smart Comments

- Don't comment on what the code does — make the code self-documenting through naming and structure instead.
- Use comments to explain *why* something is done a certain way, especially when the reason isn't visible in the code (a workaround for a library bug, a non-obvious ordering requirement).
- Document public APIs, genuinely complex algorithms, and non-obvious side effects.

## Single Responsibility

- Each function should do exactly one thing.
- Functions should be small and focused enough to be understood without scrolling.
- If a function needs a comment to explain what it does, that's a signal to split it into named sub-functions instead.

## DRY — Don't Repeat Yourself

- Extract repeated code into reusable functions once the repetition is real, not anticipated.
- Share common logic through a proper abstraction — a shared function or module, not copy-paste with tweaks.
- Maintain a single source of truth for any given piece of business logic or configuration value.

## Encapsulation

- Hide implementation details behind a clear interface; callers shouldn't need to know how a thing works to use it.
- Move nested conditionals into well-named functions or guard clauses instead of deep `if`/`else` trees.

```js
// Before
function canCheckout(cart) {
  if (cart.items.length > 0) {
    if (cart.user.isVerified) {
      if (cart.total <= cart.user.creditLimit) {
        return true;
      }
    }
  }
  return false;
}

// After
function canCheckout(cart) {
  const hasItems = cart.items.length > 0;
  const isWithinCreditLimit = cart.total <= cart.user.creditLimit;
  return hasItems && cart.user.isVerified && isWithinCreditLimit;
}
```

## Clean Structure

- Keep related code together (a feature's components, hooks, and styles in one directory, not scattered by file type).
- Organize code in a logical hierarchy that mirrors how the domain is understood.
- Use consistent file and folder naming conventions across the codebase.

## Avoiding Over-Engineering

- Only change what was asked. The simplest solution that satisfies the request comes first.
- When the right level of abstraction is unclear, ask rather than guessing toward the more elaborate option.
- Do not modify unrequested code, even if it looks improvable — a drive-by refactor in an unrelated function expands the review surface and the risk of the change.
- Do not add abstractions (interfaces, factories, plugin systems, config layers) without a concrete, current need. A single implementation doesn't need an interface "in case" a second one shows up later — that's speculative generality (YAGNI: "You Aren't Gonna Need It").
- Do not import a new dependency to solve a problem a few lines of existing code already solve.
- Do not rewrite entire files for small changes — a targeted diff is easier to review and safer to ship than a full-file rewrite.
- Do not add error handling for scenarios that cannot occur given the surrounding code's guarantees — defensive code for impossible states adds reading cost without adding safety.

### Rule of Three

- Tolerate duplication the first two times a pattern appears.
- Extract an abstraction on the third occurrence, once the actual shape of the shared logic is clear — extracting after one or two instances often guesses wrong about what's actually shared.

### Signs of Over-Engineering

- A configuration option that has only ever been set to one value.
- An interface with exactly one implementation and no test double that needs a second.
- A generic `options` object accreting fields for hypothetical future callers.
- A plugin/strategy pattern introduced before there are two strategies to switch between.

## Code Quality Maintenance

- Refactor continuously in small steps rather than deferring cleanup to a dedicated "refactor sprint."
- Fix technical debt early, while the context for why the code looks the way it does is still fresh.
- Leave code cleaner than you found it, scoped to the area you're already touching — not as license to refactor unrelated files.

## Testing

- Write a failing test before fixing a bug, so the fix is verified and the bug can't silently regress.
- Keep tests readable and maintainable — a test that's harder to understand than the code it tests has failed at its job.
- Test edge cases and error conditions explicitly, not just the happy path.

## Version Control

- Write clear, specific commit messages that explain why a change was made.
- Make small, focused commits — one logical change per commit.
- Use meaningful branch names that describe the work, not the author or the date.

## Before Delivery Checklist

- Only the requested code changed — no unrelated files touched.
- No abstraction was added without a concrete need that exists today.
- No dependency was added that duplicates something already available.
- A simpler approach was considered and ruled out, not just skipped.
- New behavior has test coverage, including at least one edge case.

© Mindrally · Apache-2.0 · Mindrally/skills

Similar skills

All skills for Code review and refactoring →

clean-code by other authors comes first.

clean-code sickn33 This skill guides code reviews and refactors using Clean Code principles, from clearer names to simpler functions. Use it when working on new code or legacy code. CX Codex +1 13,100installs clean-code wondelai clean-code — a skill that gives coding agents a readability standard: names that carry intent, small functions, disciplined comments, one error-handling style. CX Codex +1 7,200installs clean-code ciembor This Claude Code skill applies clean-code guidance to readability, naming, and function design. It activates during everyday coding and test-related tasks. CX Codex +1 683installs clean-code decebals clean-code guides your coding assistant to write readable code using DRY, KISS, and YAGNI principles. Useful when dealing with bloated methods and vague naming. CX Codex +1 448installs clean-code pproenca Loads 48 rules from Robert C. Martin's Clean Code handbook. It kicks in during code review, naming, function design, and test writing. CX Codex +1 871installs clean-architecture wondelai clean-architecture — a skill that keeps business rules independent of framework and database by enforcing one rule: source code dependencies point inward. CX Codex +1 8,000installs clean-code-guard amElnagdy clean-code-guard reviews fresh code against Clean Code and SOLID, flags the mistakes LLMs keep repeating, and runs in three modes: guard pass, live, review. CX Codex +1 4,900installs clean-code-principles AsyrafHussin clean-code-principles — a skill for architecture review and code quality: SOLID, DRY, KISS, design patterns. Useful when refactoring or weighing design decisions. CX Codex +1 1,900installs typescript-clean-code bmad-labs typescript-clean-code — a skill for reviewing and refactoring TypeScript: code smell catalogs, four detection layers, and step-by-step workflows. CX Codex +1 669installs clean-code-ts-react pproenca clean-code-ts-react adapts Robert C. Martin's Clean Code principles for TypeScript 5.x and React 19. Guides code reviews, component architecture, and refactoring sessions. CX Codex +1 238installs code-refactoring-refactor-clean rmyndharis The code-refactoring-refactor-clean Claude Code skill restructures existing code using clean-code principles and SOLID patterns. It activates for tangled modules, duplication, and testability work. CX Codex +1 154installs

From the same set247

The whole set →
lerna Gives your coding agent Lerna conventions: package layout, versioning, publishing and running scripts across a monorepo. CX Codex +1 692installs onchainkit Teaches your coding agent the OnchainKit SDK: identity, wallet, transaction, swap and frame components with TypeScript examples. CX Codex +1 682installs robocorp-cursor-rules Agent rules for writing RoboCorp RPA automation in Python: plain functions, Pydantic validation, async I/O. CX Codex +1 677installs parcel-bundler parcel-bundler — a skill that gives the agent a working set of Parcel conventions: entry points, TypeScript, CSS modules, caching and production builds. Useful when the project has no bundler config. CX Codex +1 674installs embedded-stm32 embedded-stm32 — a skill for Claude Code and Codex providing engineering rules for embedded C/C++ firmware on STM32 using the HAL. Triggers when writing peripheral drivers, handling interrupts, or setting up DMA. CX Codex +1 132installs network-troubleshooting The network-troubleshooting Claude Code skill diagnoses network failures in commands and services. It activates for DNS, TLS, proxy, connection, and package registry timeout errors. CX Codex +1 131installs readme-best-practices The readme-best-practices Claude Code skill guides README writing and review. It activates for a new project README, a rewrite, or a repository documentation check. CX Codex +1 121installs security-devsecops security-devsecops — a skill for Claude Code and Codex guides DevSecOps and AppSec practices across projects. Activates when handling credentials, user input, auth, or configuring CI/CD pipelines. CX Codex +1 117installs

Project sponsors

Companies that keep this analytics open