clean-code-skills

Use when checking code for functional correctness, backwards compatibility, logic errors, security vulnerabilities, performance issues, or missing test coverage — not style.

Use when reviewing code, pull requests, branches, diffs, or changed files for quality, correctness, security, performance, and style issues.

Use when writing, fixing, editing, or refactoring TypeScript, Python, React, or CSS code. Not for PR or diff reviews — use clean-code-reviewer for those.

Use when writing, fixing, or editing comments or documentation in any language, especially commented-out code, stale docs, metadata comments, TODO banners, redundant comments, or unclear comment value.

Use when naming or renaming identifiers in any language, especially cryptic names, ambiguous parameters, type or scope encodings, misleading side effects, or requests for clearer names.

Use when writing, fixing, or editing code in any language with duplicated logic, magic values, unclear one-liners, mixed responsibilities, clutter, arbitrary code, or inconsistent abstraction levels.

Use when writing, fixing, or editing Python async flows, coroutines, asyncio tasks, retries, timeouts, cancellation, shared mutable state across awaits, race conditions, or flaky async tests.

Use when writing, fixing, or editing Python code that touches APIs, JSON, environment variables, storage, databases, framework request objects, SDKs, generated clients, subprocesses, files, or other external boundaries.

Use when writing, fixing, or editing Python exception handling, bare except blocks, broad catches, raised values, None failures, swallowed errors, retries, fallbacks, or Result-style APIs.

Use when writing, fixing, editing, or refactoring Python functions with too many parameters, boolean flags, parameter mutation, deep nesting, mixed abstraction levels, complex conditionals, hidden side effects, dead helpers, unused public functions, mutable defaults, or unclear call sites.

Use when writing or reviewing Python modules — variables declared far from their use, module-level state with a single use site, files mixing unrelated responsibilities, domain code coupled to vendor SDKs, pass-through wrappers or empty abstractions, dependency construction inside business logic, hidden init/load/run sequences, broad __all__ exports, or package structure issues.

Use when writing, fixing, or editing Python data models, dataclasses, TypedDicts, Protocols, enums, DTOs, classes, optional fields, None absence, repeated conditionals, impossible states, object-chain access, or dynamic data structures.

Use when writing, fixing, editing, or refactoring Python code, especially weak type hints, unclear names, duplicated logic, oversized functions, stale comments, boundary gaps, exception handling, data modeling, async flows, module structure, or brittle tests.

Use when writing, fixing, editing, or refactoring Python tests, especially slow or flaky tests, skipped or focused tests, happy-path-only coverage, missing boundaries, brittle fixtures, pytest fixture misuse, monkeypatch overuse, coverage gaps, or multi-concept tests.

Use when writing, fixing, editing, or refactoring React components, hooks, state, effects, JSX, or React tests in TypeScript projects.

Use when writing, fixing, editing, or refactoring TypeScript code, especially weak types, unclear names, duplicated logic, oversized functions, stale comments, boundary gaps, error handling, data modeling, async flows, module structure, or brittle tests.

Use when writing or reviewing CSS, CSS Modules, styled-components, StyleX, or Tailwind — hardcoded hex colors or px values where tokens exist, redundant or browser-default declarations, child margins doing layout instead of flex/grid gap, deep selector chains or !important, removed focus outlines, static style={{}} props, fixed widths blocking responsive content, or repeated style blocks that should share a primitive.

Use when writing or reviewing TypeScript modules — variables declared far from their use, config flags or constants declared at the top of a file but used only at the bottom, module-level state with a single use site, files mixing unrelated responsibilities, domain code coupled to vendor SDKs, pass-through wrappers or empty abstractions, dependency construction inside business logic, hidden init/load/run sequences, or sprawling public exports.

Use when writing, fixing, editing, or refactoring React components, JSX, props, discriminated union props, conditional rendering, loading/error/empty states, render purity, component boundaries, or component composition.

Use when creating, moving, or splitting React files, owner folders, component folders, hooks, presenters, utils, CSS modules, common folders, or shared/private dependencies.

Use when writing, fixing, editing, or refactoring React hooks, custom hooks, useEffect, dependency arrays, stale closures, subscriptions, refs, or memoization.

Use when writing, fixing, editing, or refactoring React state, derived state, reducers, context, server state, loading/error/empty states, form state, or state ownership.

Use when writing, fixing, editing, or refactoring React tests with Testing Library, user-event, component rendering, accessibility queries, async UI, mocks, brittle fixtures, test data builders, or behavior coverage.

Use when writing, fixing, or editing TypeScript async flows, promises, retries, timeouts, cancellation, shared mutable state across awaits, race conditions, or flaky async tests.

Use when writing, fixing, or editing TypeScript code that touches APIs, JSON, environment variables, storage, databases, browser APIs, SDKs, generated clients, or other external boundaries.

Use when writing, fixing, or editing TypeScript error handling, catch blocks, thrown values, null failures, swallowed errors, retries, fallbacks, or Result-style APIs.

Use when writing, fixing, editing, or refactoring TypeScript functions with too many parameters, boolean flags, parameter mutation, deep nesting, mixed abstraction levels, complex conditionals, hidden side effects, dead helpers, unused exports, or unclear call sites.

Use when writing, fixing, or editing TypeScript data models, DTOs, discriminated unions, classes, object boundaries, optional fields, null or undefined absence, repeated conditionals, impossible states, or object-chain access.

Use when writing, fixing, editing, or refactoring TypeScript tests, especially slow or flaky tests, skipped or focused tests, happy-path-only coverage, missing boundaries, brittle fixtures, coverage gaps, or multi-concept tests.