Skip to main content
skill CX Codex

clean-code-ts-react — Claude Code skill: what it does, how to install

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.

MIT 238 installs ★ 227 updated 2026-08-15

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

What clean-code-ts-react does

The skill organizes 61 rules across 11 categories, ranked by cognitive cost across the lifecycle of a code change. Categories range from naming conventions and function design to error handling, testing, and boundaries. Code samples lean on TypeScript 5.x features like satisfies and branded types, alongside React 19 idioms.

Unlike generic style checklists, each rule explicitly defines when not to follow it. For instance, loop counters can stay as i, and single-use code avoids premature DRY abstractions. An entire section covers direct conflicts between principles, such as DRY versus Single Responsibility or tiny functions versus deep modules.

This skill ignores React runtime mechanics and compiler tuning. For Server Components API details or tsconfig performance, use dedicated react and typescript skills instead.

What it helps with

  • review pull requests for clear naming and sensible abstraction levels
  • resolve tensions between DRY and the Single Responsibility Principle
  • restructure bloated components and hooks into smaller single-purpose units
  • choose between thrown exceptions and Result types for error handling

Example prompts for the agent

  • Review this React component for naming clarity and hidden side effects
  • Help me refactor this TypeScript module to separate commands from queries
  • Check if this custom hook introduces unnecessary abstractions

How to install clean-code-ts-react

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill clean-code-ts-react -a claude-code

2Manually: put the files in place

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

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

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

Questions about clean-code-ts-react

How do I install clean-code-ts-react in Claude Code?

Run npx skills add pproenca/dot-skills --skill clean-code-ts-react -a claude-code in your terminal.

What does clean-code-ts-react do?

It brings 61 Clean Code guidelines into modern TypeScript 5.x and React 19 projects, guiding naming, error handling, component structure, and trade-offs.

Does clean-code-ts-react cover React 19 APIs or tsconfig settings?

No. It focuses purely on readability and design principles. Use the react skill for framework APIs and the typescript skill for compiler performance.

Source text

SKILL.md · MIT
---
name: clean-code-ts-react
description: Use when writing, reviewing, or refactoring TypeScript or React code for craftsmanship — naming, function and component shape, error handling, data modeling, tests, and abstraction. Translates Robert C. Martin's Clean Code principles into modern TS+React idioms (TS 5.x, React 19), with first-class "When NOT to apply" guidance and a Meta category for principle conflicts (DRY vs SRP, small functions vs deep modules, type safety vs ergonomics). Triggers on code review, refactoring for clarity, naming, function/component design, "is this clean?", "make this more readable", "right abstraction?" — even when the user doesn't say "clean code". Does NOT cover React-specific APIs (RSC, hooks API surface) — use the `react` skill. Does NOT cover TS compiler perf or tsconfig — use the `typescript` skill.
---

# Robert C. Martin (Uncle Bob) TypeScript 5.x + React 19 Best Practices

Craftsmanship principles from Robert C. Martin's *Clean Code* (2008), re-expressed for modern TypeScript and React. Contains **61 rules across 11 categories**, prioritized by cognitive cost across a code change's lifetime. Examples use TS 5.x and React 19 idioms — but the rules are about timeless principles, not specific APIs.

## What Makes This Skill Different

Three things set this apart from a generic clean-code copy:

1. **Modern idioms as vehicle.** Examples use TS 5.x (`satisfies`, branded types, discriminated unions, `const` type parameters) and React 19 (function components, hooks, `use()`, Server Components where relevant). But the rule is always the principle, never the syntax.
2. **"When NOT to apply" is first-class.** Every rule has 2-3 concrete scenarios where the principle should bend — not generic disclaimers, real situations. Loop counters can be `i`. Single-use code shouldn't be DRY. Some HOCs are unavoidable.
3. **Meta category for principle conflicts.** Category 11 names the most common tensions explicitly — DRY vs Single Responsibility, small functions vs deep modules (Ousterhout), type precision vs ergonomic APIs, tests as spec vs documentation. The mark of seniority is knowing which to bend.

## When to Apply

Reference these guidelines when:
- Writing new TypeScript or React code and wanting craftsmanship feedback
- Reviewing a pull request for clarity, naming, or abstraction
- Refactoring existing code for readability or maintainability
- Designing function, hook, or component APIs
- Deciding whether to extract, abstract, or duplicate
- Resolving a tension between two clean-code rules (see Category 11)

Skip this skill and use:
- **`react`** for React 19 API patterns (concurrent rendering, Server Components, ref-as-prop, `useActionState`, `<Context>`-as-provider)
- **`typescript`** for compiler performance, tsconfig tuning, type-system perf
- **`refactor`** for mechanical refactoring workflows
- **`tdd`** for the TDD workflow itself

## Rule Categories by Priority

Order reflects **cognitive cost across a change's lifetime** (read → understand → modify → verify → ship → maintain). Earlier stages cascade — bad names taint every read.

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Meaningful Names | CRITICAL | `name-` | 8 |
| 2 | Functions, Components & Hooks | CRITICAL | `func-` | 8 |
| 3 | Self-Documentation (Types & Comments) | HIGH | `doc-` | 5 |
| 4 | Formatting (Beyond Prettier) | HIGH | `fmt-` | 4 |
| 5 | Error Handling | HIGH | `err-` | 7 |
| 6 | Data Shape & Immutability | MEDIUM-HIGH | `data-` | 6 |
| 7 | Boundaries | MEDIUM-HIGH | `bound-` | 4 |
| 8 | Composition over Inheritance | MEDIUM-HIGH | `comp-` | 6 |
| 9 | Tests | MEDIUM | `test-` | 5 |
| 10 | Emergence & Simple Design | MEDIUM | `emerge-` | 4 |
| 11 | **Meta: When Principles Conflict** | MEDIUM | `meta-` | 4 |

**Total: 61 rules.**

## Quick Reference

### 1. Meaningful Names (CRITICAL)

- [`name-intention-revealing`](references/name-intention-revealing.md) — Use names that reveal intent
- [`name-avoid-disinformation`](references/name-avoid-disinformation.md) — Avoid misleading names
- [`name-meaningful-distinctions`](references/name-meaningful-distinctions.md) — Make meaningful distinctions
- [`name-component-pascal-case`](references/name-component-pascal-case.md) — Components are PascalCase noun phrases
- [`name-hook-use-prefix`](references/name-hook-use-prefix.md) — Hooks are `useX` verb phrases
- [`name-handler-convention`](references/name-handler-convention.md) — Event handlers use `onX` / `handleX`
- [`name-boolean-predicate`](references/name-boolean-predicate.md) — Boolean variables use `is`/`has`/`can`
- [`name-types-pascal-case`](references/name-types-pascal-case.md) — Types and interfaces are PascalCase

### 2. Functions, Components & Hooks (CRITICAL)

- [`func-small`](references/func-small.md) — Keep functions, components & hooks small
- [`func-one-thing`](references/func-one-thing.md) — Do one thing
- [`func-abstraction-level`](references/func-abstraction-level.md) — One level of abstraction per function
- [`func-minimize-arguments`](references/func-minimize-arguments.md) — Prefer object parameters over long lists
- [`func-no-side-effects`](references/func-no-side-effects.md) — Avoid hidden side effects (especially in render)
- [`func-command-query-separation`](references/func-command-query-separation.md) — Separate commands from queries
- [`func-dry`](references/func-dry.md) — DRY — until concepts diverge
- [`func-custom-hook-extract`](references/func-custom-hook-extract.md) — Extract custom hooks for reusable stateful logic

### 3. Self-Documentation: Types & Comments (HIGH)

- [`doc-types-over-comments`](references/doc-types-over-comments.md) — Prefer types over comments
- [`doc-satisfies-narrows-with-check`](references/doc-satisfies-narrows-with-check.md) — Use `satisfies` for inferred-but-checked values
- [`doc-jsdoc-public-api`](references/doc-jsdoc-public-api.md) — JSDoc for public APIs and non-obvious side effects
- [`doc-avoid-redundant-comments`](references/doc-avoid-redundant-comments.md) — Avoid redundant comments
- [`doc-delete-commented-out-code`](references/doc-delete-commented-out-code.md) — Delete commented-out code

### 4. Formatting Beyond Prettier (HIGH)

- [`fmt-vertical-density`](references/fmt-vertical-density.md) — Keep related code close, unrelated far
- [`fmt-newspaper-order`](references/fmt-newspaper-order.md) — Order files top-down like a newspaper
- [`fmt-team-rules-over-preference`](references/fmt-team-rules-over-preference.md) — Team conventions over personal preference
- [`fmt-imports-grouped`](references/fmt-imports-grouped.md) — Group imports by source

### 5. Error Handling (HIGH)

- [`err-early-return`](references/err-early-return.md) — Use early returns to flatten error paths
- [`err-result-vs-throw`](references/err-result-vs-throw.md) — Choose throw vs Result deliberately
- [`err-narrow-unknown`](references/err-narrow-unknown.md) — Always narrow `unknown` in catch blocks
- [`err-error-boundaries`](references/err-error-boundaries.md) — Use error boundaries for render-time failures
- [`err-suspense-for-loading`](references/err-suspense-for-loading.md) — Use Suspense for loading states
- [`err-no-swallow`](references/err-no-swallow.md) — Never swallow errors silently
- [`err-null-vs-undefined`](references/err-null-vs-undefined.md) — Pick `null` OR `undefined` per domain

### 6. Data Shape & Immutability (MEDIUM-HIGH)

- [`data-discriminated-unions-over-flags`](references/data-discriminated-unions-over-flags.md) — Discriminated unions over boolean flags
- [`data-readonly-by-default`](references/data-readonly-by-default.md) — Mark read-only data `readonly`
- [`data-branded-types`](references/data-branded-types.md) — Brand types for domain invariants
- [`data-dto-vs-domain`](references/data-dto-vs-domain.md) — Separate DTOs from domain types
- [`data-demeter-prop-drilling`](references/data-demeter-prop-drilling.md) — Prop drilling often smells like Demeter
- [`data-structural-typing-pitfalls`](references/data-structural-typing-pitfalls.md) — Beware structural typing aliasing

### 7. Boundaries (MEDIUM-HIGH)

- [`bound-wrap-third-party-hooks`](references/bound-wrap-third-party-hooks.md) — Wrap third-party hooks in custom hooks
- [`bound-learning-tests`](references/bound-learning-tests.md) — Write learning tests for third-party behavior
- [`bound-isolate-framework`](references/bound-isolate-framework.md) — Isolate framework-specific code at the edges
- [`bound-type-assertions-at-edges`](references/bound-type-assertions-at-edges.md) — Type assertions belong only at boundaries

### 8. Composition over Inheritance (MEDIUM-HIGH)

- [`comp-children-over-props`](references/comp-children-over-props.md) — Compose with `children` over configuration props
- [`comp-small-components`](references/comp-small-components.md) — Keep components small and cohesive
- [`comp-avoid-hoc-stacks`](references/comp-avoid-hoc-stacks.md) — Avoid higher-order component stacks
- [`comp-context-only-when-needed`](references/comp-context-only-when-needed.md) — Context for DI, not prop avoidance
- [`comp-render-props-vs-hooks`](references/comp-render-props-vs-hooks.md) — Prefer hooks over render props for logic reuse
- [`comp-separate-construction-from-use`](references/comp-separate-construction-from-use.md) — Separate setup from rendering

### 9. Tests (MEDIUM)

- [`test-behavior-not-implementation`](references/test-behavior-not-implementation.md) — Test behavior, not implementation
- [`test-mock-at-boundaries`](references/test-mock-at-boundaries.md) — Mock only at true boundaries
- [`test-first-principles`](references/test-first-principles.md) — Apply FIRST principles
- [`test-one-concept`](references/test-one-concept.md) — One concept (not one assert) per test
- [`test-clean-as-production`](references/test-clean-as-production.md) — Test code deserves production-grade care

### 10. Emergence & Simple Design (MEDIUM)

- [`emerge-four-rules`](references/emerge-four-rules.md) — Apply the four rules of simple design in order
- [`emerge-yagni-types`](references/emerge-yagni-types.md) — Avoid premature type generics
- [`emerge-premature-abstraction`](references/emerge-premature-abstraction.md) — Resist premature abstraction
- [`emerge-reveal-intent`](references/emerge-reveal-intent.md) — Maximize expressiveness — code as communication

### 11. Meta: When Principles Conflict (MEDIUM)

**This is the signature category** — explicit guidance on when one clean-code principle yields to another.

- [`meta-dry-vs-srp`](references/meta-dry-vs-srp.md) — Bend DRY when concepts drift apart
- [`meta-small-vs-deep`](references/meta-small-vs-deep.md) — Small functions lose to deep modules when indirection > comprehension
- [`meta-types-vs-ergonomics`](references/meta-types-vs-ergonomics.md) — Type safety loses to ergonomics at stable boundaries
- [`meta-tests-as-spec-vs-doc`](references/meta-tests-as-spec-vs-doc.md) — Pick tests-as-spec or tests-as-documentation per file

## How to Use

For an ad-hoc question ("is this naming OK?", "should I extract this?"), jump straight to the relevant rule file via the Quick Reference above.

For a code review or refactor, scan the categories in priority order — names and function shape first (highest cascade), then errors and data shape, then composition and tests. The category-major sweep is more efficient than file-major.

When two principles seem to disagree, read the corresponding Meta rule (Category 11). Pick the principle that wins, and document the call.

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for adding new rules |
| [metadata.json](metadata.json) | Version and reference information |

## Related Skills

- `.experimental/clean-code` — Original language-agnostic clean code (Java examples). This skill is the TS+React sibling.
- `.curated/react` — React 19-specific patterns (Server Components, concurrent rendering, ref-as-prop).
- `.curated/typescript` — TS compiler performance and tsconfig tuning.
- `.curated/refactor` — Mechanical refactoring workflows.
- `.curated/tdd` — The TDD workflow itself.

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Code review and refactoring →

From the same set139

The whole set →
threat-model threat-model maps attack surfaces and trust boundaries across a codebase by tracing untrusted inputs directly to execution sinks. CX Codex +1 243installs opencode-ts The opencode-ts skill guides TypeScript implementation, tests, and refactoring in Effect-based projects. It gives the agent a workflow tied to the project’s architecture and conventions. CX Codex +1 240installs exec-plan exec-plan manages self-contained Markdown execution plans across agent sessions for tasks touching more than three files or taking over an hour. CX Codex +1 239installs graph-schema graph-schema is a Claude Code skill for designing, reviewing, and refactoring graph database schemas. It activates for node and relationship modeling or when mapping a domain into a graph. CX Codex +1 239installs cli-for-agents cli-for-agents is a Claude Code skill for designing and reviewing CLIs used by AI agents and automation. It applies to work on subcommands, flags, help text, and error messages. CX Codex +1 237installs eval-mcp eval-mcp measures MCP tool schema quality and Claude's tool selection accuracy. Detects confusing descriptions and runs intent benchmarks. CX Codex +1 234installs threat-patch threat-patch turns scanner findings or a threat model into small code patches, each with a short write-up and test steps. CX Codex +1 232installs diagram-quality diagram-quality enforces PlantUML quality and rendering rules for the agent-uml canvas to avoid HTTP 400 errors and unclickable elements in diagram workflows. CX Codex +1 230installs

Project sponsors

Companies that keep this analytics open