Skip to main content
affpapa.org
RU EN
skill CX Codex

code-simplifier · pproenca — Claude Code skill: simplify code, keep behavior

A skill that gives AI agents 47 rules for cleaning up recently changed code without altering what it does.

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

What code-simplifier does

code-simplifier is a rule set an AI agent follows when simplifying code. It ships 47 rules in 8 categories, ordered by impact: context discovery and behavior preservation come first, language idioms last. Each rule carries an explanation, a wrong-vs-right example, and impact notes.

The core idea is restraint. The agent reads project conventions before touching anything, then changes how code is written, never what it does. Diffs stay small and scoped to recently modified files. Return values, error messages, public signatures and side effects are left alone. Rules include flow-early-return for cutting nesting, name-intention-revealing for names that say what they mean, and dead-delete-not-comment for removing dead code instead of commenting it out.

It installs into Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. On Claude the file lands at ~/.claude/skills/code-simplifier/SKILL.md. Worth checking before you install: if your project has no CLAUDE.md and no lint config, the agent has nothing to match, so the Context Discovery rules have little to work with.

What it helps with

  • flatten deep nesting in a function you just edited
  • pull repeated conditionals into one branch
  • rename variables so the name explains the intent
  • delete dead code instead of commenting it out
  • match edits to project style rather than generic advice

Example prompts for the agent

  • Simplify the code in src/parser.ts I just changed, keep behavior identical
  • Run code-simplifier over my last commit and show the diff
  • Reduce nesting in this function using early returns

How to install code-simplifier

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill code-simplifier -a claude-code

2Manually: put the files in place

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

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

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

Questions about code-simplifier

How do I install code-simplifier in Claude?

Run npx skills add pproenca/dot-skills --skill code-simplifier -a claude-code. The skill ends up at ~/.claude/skills/code-simplifier/SKILL.md.

What does code-simplifier do?

It hands the agent 47 simplification rules across 8 categories: project context, behavior preservation, scope, control flow, naming, duplication, dead code and language idioms. The agent changes how code reads, not what it does.

Which platforms does the skill support?

Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. The install command differs only by the platform flag, such as -a cursor or -a codex.

Source text

SKILL.md · MIT 
---
name: code-simplifier
description: Code simplification skill for improving clarity, consistency, and maintainability while preserving exact behavior. Use when simplifying code, reducing complexity, cleaning up recent changes, applying refactoring patterns, or improving readability. Triggers on tasks involving code cleanup, simplification, refactoring, or readability improvements.
---

# Community Code Simplification Best Practices

Comprehensive code simplification guide for AI agents and LLMs. Contains 47 rules across 8 categories, prioritized by impact from critical (context discovery, behavior preservation) to incremental (language idioms). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics.

## Core Principles

1. **Context First**: Understand project conventions before making any changes
2. **Behavior Preservation**: Change how code is written, never what it does
3. **Scope Discipline**: Focus on recently modified code, keep diffs small
4. **Clarity Over Brevity**: Explicit, readable code beats clever one-liners

## When to Apply

Reference these guidelines when:
- Simplifying or cleaning up recently modified code
- Reducing nesting, complexity, or duplication
- Improving naming and readability
- Applying language-specific idiomatic patterns
- Reviewing code for maintainability issues

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Context Discovery | CRITICAL | `ctx-` | 4 |
| 2 | Behavior Preservation | CRITICAL | `behave-` | 6 |
| 3 | Scope Management | HIGH | `scope-` | 5 |
| 4 | Control Flow Simplification | HIGH | `flow-` | 9 |
| 5 | Naming and Clarity | MEDIUM-HIGH | `name-` | 6 |
| 6 | Duplication Reduction | MEDIUM | `dup-` | 5 |
| 7 | Dead Code Elimination | MEDIUM | `dead-` | 5 |
| 8 | Language Idioms | LOW-MEDIUM | `idiom-` | 7 |

## Quick Reference

### 1. Context Discovery (CRITICAL)

- [`ctx-read-claude-md`](references/ctx-read-claude-md.md) - Always read CLAUDE.md before simplifying
- [`ctx-detect-lint-config`](references/ctx-detect-lint-config.md) - Check for linting and formatting configs
- [`ctx-follow-existing-patterns`](references/ctx-follow-existing-patterns.md) - Match existing code style in file and project
- [`ctx-project-over-generic`](references/ctx-project-over-generic.md) - Project conventions override generic best practices

### 2. Behavior Preservation (CRITICAL)

- [`behave-preserve-outputs`](references/behave-preserve-outputs.md) - Preserve all return values and outputs
- [`behave-preserve-errors`](references/behave-preserve-errors.md) - Preserve error messages, types, and handling
- [`behave-preserve-api`](references/behave-preserve-api.md) - Preserve public function signatures and types
- [`behave-preserve-side-effects`](references/behave-preserve-side-effects.md) - Preserve side effects (logging, I/O, state changes)
- [`behave-no-semantics-change`](references/behave-no-semantics-change.md) - Forbid subtle semantic changes
- [`behave-verify-before-commit`](references/behave-verify-before-commit.md) - Verify behavior preservation before finalizing

### 3. Scope Management (HIGH)

- [`scope-recent-code-only`](references/scope-recent-code-only.md) - Focus on recently modified code only
- [`scope-minimal-diff`](references/scope-minimal-diff.md) - Keep changes small and reviewable
- [`scope-no-unrelated-refactors`](references/scope-no-unrelated-refactors.md) - No unrelated refactors
- [`scope-no-global-rewrites`](references/scope-no-global-rewrites.md) - Avoid global rewrites and architectural changes
- [`scope-respect-boundaries`](references/scope-respect-boundaries.md) - Respect module and component boundaries

### 4. Control Flow Simplification (HIGH)

- [`flow-early-return`](references/flow-early-return.md) - Use early returns to reduce nesting
- [`flow-guard-clauses`](references/flow-guard-clauses.md) - Use guard clauses for preconditions
- [`flow-no-nested-ternaries`](references/flow-no-nested-ternaries.md) - Never use nested ternary operators
- [`flow-explicit-over-dense`](references/flow-explicit-over-dense.md) - Prefer explicit control flow over dense expressions
- [`flow-flatten-nesting`](references/flow-flatten-nesting.md) - Flatten deep nesting to maximum 2-3 levels
- [`flow-single-responsibility`](references/flow-single-responsibility.md) - Each code block should do one thing
- [`flow-positive-conditions`](references/flow-positive-conditions.md) - Prefer positive conditions over double negatives
- [`flow-optional-chaining`](references/flow-optional-chaining.md) - Use optional chaining and nullish coalescing
- [`flow-boolean-simplification`](references/flow-boolean-simplification.md) - Simplify boolean expressions

### 5. Naming and Clarity (MEDIUM-HIGH)

- [`name-intention-revealing`](references/name-intention-revealing.md) - Use intention-revealing names
- [`name-nouns-for-data`](references/name-nouns-for-data.md) - Use nouns for data, verbs for actions
- [`name-avoid-abbreviations`](references/name-avoid-abbreviations.md) - Avoid cryptic abbreviations
- [`name-consistent-vocabulary`](references/name-consistent-vocabulary.md) - Use consistent vocabulary throughout
- [`name-avoid-generic`](references/name-avoid-generic.md) - Avoid generic names
- [`name-string-interpolation`](references/name-string-interpolation.md) - Prefer string interpolation over concatenation

### 6. Duplication Reduction (MEDIUM)

- [`dup-rule-of-three`](references/dup-rule-of-three.md) - Apply the rule of three
- [`dup-no-single-use-helpers`](references/dup-no-single-use-helpers.md) - Avoid single-use helper functions
- [`dup-extract-for-clarity`](references/dup-extract-for-clarity.md) - Extract only when it improves clarity
- [`dup-avoid-over-abstraction`](references/dup-avoid-over-abstraction.md) - Prefer duplication over premature abstraction
- [`dup-data-driven`](references/dup-data-driven.md) - Use data-driven patterns over repetitive conditionals

### 7. Dead Code Elimination (MEDIUM)

- [`dead-remove-unused`](references/dead-remove-unused.md) - Delete unused code artifacts
- [`dead-delete-not-comment`](references/dead-delete-not-comment.md) - Delete code, never comment it out
- [`dead-remove-obvious-comments`](references/dead-remove-obvious-comments.md) - Remove comments that state the obvious
- [`dead-keep-why-comments`](references/dead-keep-why-comments.md) - Keep comments that explain why, not what
- [`dead-remove-todo-fixme`](references/dead-remove-todo-fixme.md) - Remove stale TODO/FIXME comments

### 8. Language Idioms (LOW-MEDIUM)

- [`idiom-ts-strict-types`](references/idiom-ts-strict-types.md) - Use strict types over any (TypeScript)
- [`idiom-ts-const-assertions`](references/idiom-ts-const-assertions.md) - Use const assertions and readonly (TypeScript)
- [`idiom-rust-question-mark`](references/idiom-rust-question-mark.md) - Use ? for error propagation (Rust)
- [`idiom-rust-iterator-chains`](references/idiom-rust-iterator-chains.md) - Use iterator chains when clearer (Rust)
- [`idiom-python-comprehensions`](references/idiom-python-comprehensions.md) - Use comprehensions for simple transforms (Python)
- [`idiom-go-error-handling`](references/idiom-go-error-handling.md) - Handle errors immediately (Go)
- [`idiom-prefer-language-builtins`](references/idiom-prefer-language-builtins.md) - Prefer language and stdlib builtins

## Workflow

1. **Discover context**: Read CLAUDE.md, lint configs, examine existing patterns
2. **Identify scope**: Focus on recently modified code unless asked to expand
3. **Apply transformations**: Use rules in priority order (CRITICAL first)
4. **Verify behavior**: Ensure outputs, errors, and side effects remain identical
5. **Keep diffs minimal**: Small, focused changes that are easy to review

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

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

© pproenca · MIT · pproenca/dot-skills

Similar skills

Everything for Code review and refactoring →

code-simplifier by other authors comes first.

code-simplifier rtk-ai Reviews Rust code in RTK to remove over-engineering and needless allocations. It applies idiomatic simplifications without altering runtime behavior. CX Codex +1 2,100installs code-simplifier anthropics Rewrites code you just touched so it reads cleaner, without changing what it does. Handy right after a messy edit. CX Codex +1 1,800installs code-simplifier yamapan (https://github.com/aktsmm) A skill for refactoring code after a coding session: drops nested ternaries, dense one-liners and restating comments without changing behaviour. CX Codex +1 365installs simplify brianlovin Rewrites code you just wrote so it reads better: less nesting, fewer duplicates, clearer names. Behaviour stays exactly as it was. CX Codex +1 20,100installs principle-minimize-reader-load backnotprop A skill that spots unnecessary layers of abstraction and hidden state slowing down code comprehension. Use it when reviewing complex code where the logic is hard to trace. CX Codex +1 5,200installs principal-engineering riekelt Enforces core engineering discipline for AI agents: mandates pre-change checkpoints, bans silent error suppression, and requires evidence from real code. CX Codex +1 18,000installs antislop-code miqdadbadjuber This skill filters out comments that look AI-generated: ones that repeat what the code shows, chop the flow into steps, or decorate section headers. It keeps comments with real information and never touches executable code. CX Codex +1 5,800installs gem-code-simplifier official github A refactoring subagent that removes dead code and drops complexity. Handy when cleaning up messy logic without altering existing behavior. ★ 40,418repo stars improve-code-quality wondelai Guides untested prototypes toward production code with tests, clean boundaries, and system resilience. Useful when code works but feels too fragile to touch. CX Codex +1 2,300installs

From the same set45

react-hook-form Optimizes client-side forms using React Hook Form 7.82.0 and prevents unnecessary re-renders across field subscriptions, validation, and controlled UI inputs. CX Codex +1 3,000installs emilkowal-animations A set of 58 web animation rules based on Emil Kowalski's work for React and Framer Motion. Helps tune easing curves, gestures, and UI timing. CX Codex +1 2,800installs nuqs A skill with 39 nuqs rules covering typed parsers, adapters, Server Components and URL update performance. Useful when an agent writes or refactors URL state code. CX Codex +1 2,300installs clean-architecture A skill with 42 rules from Robert C. Martin's book: it tells the agent which way dependencies should point and where layer boundaries belong. CX Codex +1 2,000installs expo-react-native-performance Performance guidelines with 42 prioritized rules for Expo React Native apps. Helps agents refactor startup bottlenecks, list virtualization, re-renders, and animations. CX Codex +1 1,500installs framer-motion Optimizes React animations using Framer Motion guidelines: slashes bundle size, eliminates unnecessary re-renders, and polishes gesture or scroll transitions. CX Codex +1 1,100installs msw A skill with 45 rules for Mock Service Worker v2: setup, handlers, test integration, GraphQL. Useful when your agent writes or fixes HTTP mocks. CX Codex +1 842installs clean-code A skill that feeds the agent 48 rules on naming, functions, errors and tests, drawn from Robert C. Martin's book with modern fixes. Useful during reviews and refactors. CX Codex +1 842installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor