Code simplification

Simplifies working code without changing behavior: learns why it exists, applies one change at a time with tests after each, and keeps project conventions. Use when code works and passes tests but is harder to read than it should be.

CodingPack: Agent Skills by Addy Osmani331 linescode-simplification
Author
Source
addyosmani/agent-skills/skills/code-simplification @ 8c99fa3
License
MIT · Copyright (c) 2025 Addy Osmani

About this skill

What it does

The skill makes working code easier to read without changing what it does. SKILL.md names Anthropic's Claude Code Simplifier plugin as its inspiration and recasts it as a process for any agent. Five rules frame it: identical behavior (same outputs, errors and side effects; existing tests pass unmodified); the project's conventions from CLAUDE.md and neighbouring code; clear over compact and clever; no over-simplifying, such as inlining a helper that names a concept; and a scope limited to recently changed code.

First the agent finds out why the code is the way it is — callers, edge cases, tests, git blame — before touching it (Chesterton's fence). Then it looks for signals from three tables, such as deep nesting, functions over 50 lines, nested ternaries, boolean flags, vague names and dead code. Simplifications go in one at a time, with tests after each and a revert on red; past 500 touched lines, a codemod or AST transform replaces hand edits. A final before-and-after comparison reverts anything that ended up harder to follow. Refactoring ships apart from features and fixes. Examples cover TypeScript, Python and React.

The folder holds only SKILL.md and the licence.

When to use it, and when not

Use it once a feature works and tests pass but the code reads heavier than it should, when review flags complexity, or after a merge added duplication.

The skill names its exceptions: already clean code, code you do not understand yet, hot paths where simpler is measurably slower, a module about to be rewritten.

How to run it

The install command below puts the folder in place. The agent picks the skill up by its description when asked to simplify or clean up working code; to call it yourself:

  • Claude Code: /code-simplification, or ask for the skill by name.
  • Codex: $code-simplification.
  • Cursor: type / in the Agent chat and pick code-simplification.

Example: /code-simplification Simplify what I changed in src/billing/invoice.ts without changing behavior.

It does not call other skills.

How it differs from similar skills

Code simplifier from Sentry is based on the same Anthropic agent but stays a short pass. It has no step to learn why the code is the way it is, runs no tests after each change and brings its own style rules, such as function over arrow functions. Safe refactoring from our catalog covers any restructuring and starts with characterization tests where coverage is thin, with explicit stop points. Code simplification relies on the existing tests passing unmodified and goes further into readability. Improve codebase architecture works at module level across the codebase, reports in HTML and runs only when called. Code comments cleanup touches comments only.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/code-simplification/SKILL.md https://anymodel.org/en/skills/addy-osmani/code-simplification/SKILL.md -o ~/.claude/skills/code-simplification/LICENSE https://anymodel.org/en/skills/addy-osmani/code-simplification/LICENSE
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/code-simplification/SKILL.md https://anymodel.org/en/skills/addy-osmani/code-simplification/SKILL.md -o ~/.agents/skills/code-simplification/LICENSE https://anymodel.org/en/skills/addy-osmani/code-simplification/LICENSE
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.claude\skills\code-simplification" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/code-simplification/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.agents\skills\code-simplification" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/code-simplification/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/addy-osmani/code-simplification/SKILL.md

SKILL.md

Raw

Code Simplification

Inspired by the Claude Code Simplifier plugin. Adapted here as a model-agnostic, process-driven skill for any AI coding agent.

Overview

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"

When to Use

  • After a feature is working and tests pass, but the implementation feels heavier than it needs to be
  • During code review when readability or complexity issues are flagged
  • When you encounter deeply nested logic, long functions, or unclear names
  • When refactoring code written under time pressure
  • When consolidating related logic scattered across files
  • After merging changes that introduced duplication or inconsistency

When NOT to use:

  • Code is already clean and readable — don't simplify for the sake of it
  • You don't understand what the code does yet — comprehend before you simplify
  • The code is performance-critical and the "simpler" version would be measurably slower
  • You're about to rewrite the module entirely — simplifying throwaway code wastes effort

The Five Principles

1. Preserve Behavior Exactly

Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.

ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior?
→ Does this preserve the same side effects and ordering?
→ Do all existing tests still pass without modification?

2. Follow Project Conventions

Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:

1. Read CLAUDE.md / project conventions
2. Study how neighboring code handles similar patterns
3. Match the project's style for:
   - Import ordering and module system
   - Function declaration style
   - Naming conventions
   - Error handling patterns
   - Type annotation depth

Simplification that breaks project consistency is not simplification — it's churn.

3. Prefer Clarity Over Cleverness

Explicit code is better than compact code when the compact version requires a mental pause to parse.

// UNCLEAR: Dense ternary chain
const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';

// CLEAR: Readable mapping
function getStatusLabel(item: Item): string {
  if (item.isNew) return 'New';
  if (item.isUpdated) return 'Updated';
  if (item.isArchived) return 'Archived';
  return 'Active';
}
// UNCLEAR: Chained reduces with inline logic
const result = items.reduce((acc, item) => ({
  ...acc,
  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
}), {});

// CLEAR: Named intermediate step
const countById = new Map<string, number>();
for (const item of items) {
  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
}

4. Maintain Balance

Simplification has a failure mode: over-simplification. Watch for these traps:

  • Inlining too aggressively — removing a helper that gave a concept a name makes the call site harder to read
  • Combining unrelated logic — two simple functions merged into one complex function is not simpler
  • Removing "unnecessary" abstraction — some abstractions exist for extensibility or testability, not complexity
  • Optimizing for line count — fewer lines is not the goal; easier comprehension is

5. Scope to What Changed

Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.

The Simplification Process

Step 1: Understand Before Touching (Chesterton's Fence)

Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.

BEFORE SIMPLIFYING, ANSWER:
- What is this code's responsibility?
- What calls it? What does it call?
- What are the edge cases and error paths?
- Are there tests that define the expected behavior?
- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
- Check git blame: what was the original context for this code?

If you can't answer these, you're not ready to simplify. Read more context first.

Step 2: Identify Simplification Opportunities

Scan for these patterns — each one is a concrete signal, not a vague smell:

Structural complexity:

Pattern Signal Simplification
Deep nesting (3+ levels) Hard to follow control flow Extract conditions into guard clauses or helper functions
Long functions (50+ lines) Multiple responsibilities Split into focused functions with descriptive names
Nested ternaries Requires mental stack to parse Replace with if/else chains, switch, or lookup objects
Boolean parameter flags doThing(true, false, true) Replace with options objects or separate functions
Repeated conditionals Same if check in multiple places Extract to a well-named predicate function

Naming and readability:

Pattern Signal Simplification
Generic names data, result, temp, val, item Rename to describe the content: userProfile, validationErrors
Abbreviated names usr, cfg, btn, evt Use full words unless the abbreviation is universal (id, url, api)
Misleading names Function named get that also mutates state Rename to reflect actual behavior
Comments explaining "what" // increment counter above count++ Delete the comment — the code is clear enough
Comments explaining "why" // Retry because the API is flaky under load Keep these — they carry intent the code can't express

Redundancy:

Pattern Signal Simplification
Duplicated logic Same 5+ lines in multiple places Extract to a shared function
Dead code Unreachable branches, unused variables, commented-out blocks Remove (after confirming it's truly dead)
Unnecessary abstractions Wrapper that adds no value Inline the wrapper, call the underlying function directly
Over-engineered patterns Factory-for-a-factory, strategy-with-one-strategy Replace with the simple direct approach
Redundant type assertions Casting to a type that's already inferred Remove the assertion

Step 3: Apply Changes Incrementally

Make one simplification at a time. Run tests after each change. Submit refactoring changes separately from feature or bug fix changes. A PR that refactors and adds a feature is two PRs — split them.

FOR EACH SIMPLIFICATION:
1. Make the change
2. Run the test suite
3. If tests pass → commit (or continue to next simplification)
4. If tests fail → revert and reconsider

Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.

The Rule of 500: If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.

Step 4: Verify the Result

After all simplifications, step back and evaluate the whole:

COMPARE BEFORE AND AFTER:
- Is the simplified version genuinely easier to understand?
- Did you introduce any new patterns inconsistent with the codebase?
- Is the diff clean and reviewable?
- Would a teammate approve this change?

If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.

Language-Specific Guidance

TypeScript / JavaScript

// SIMPLIFY: Unnecessary async wrapper
// Before
async function getUser(id: string): Promise<User> {
  return await userService.findById(id);
}
// After
function getUser(id: string): Promise<User> {
  return userService.findById(id);
}

// SIMPLIFY: Verbose conditional assignment
// Before
let displayName: string;
if (user.nickname) {
  displayName = user.nickname;
} else {
  displayName = user.fullName;
}
// After
const displayName = user.nickname || user.fullName;

// SIMPLIFY: Manual array building
// Before
const activeUsers: User[] = [];
for (const user of users) {
  if (user.isActive) {
    activeUsers.push(user);
  }
}
// After
const activeUsers = users.filter((user) => user.isActive);

// SIMPLIFY: Redundant boolean return
// Before
function isValid(input: string): boolean {
  if (input.length > 0 && input.length < 100) {
    return true;
  }
  return false;
}
// After
function isValid(input: string): boolean {
  return input.length > 0 && input.length < 100;
}

Python

# SIMPLIFY: Verbose dictionary building
# Before
result = {}
for item in items:
    result[item.id] = item.name
# After
result = {item.id: item.name for item in items}

# SIMPLIFY: Nested conditionals with early return
# Before
def process(data):
    if data is not None:
        if data.is_valid():
            if data.has_permission():
                return do_work(data)
            else:
                raise PermissionError("No permission")
        else:
            raise ValueError("Invalid data")
    else:
        raise TypeError("Data is None")
# After
def process(data):
    if data is None:
        raise TypeError("Data is None")
    if not data.is_valid():
        raise ValueError("Invalid data")
    if not data.has_permission():
        raise PermissionError("No permission")
    return do_work(data)

React / JSX

// SIMPLIFY: Verbose conditional rendering
// Before
function UserBadge({ user }: Props) {
  if (user.isAdmin) {
    return <Badge variant="admin">Admin</Badge>;
  } else {
    return <Badge variant="default">User</Badge>;
  }
}
// After
function UserBadge({ user }: Props) {
  const variant = user.isAdmin ? 'admin' : 'default';
  const label = user.isAdmin ? 'Admin' : 'User';
  return <Badge variant={variant}>{label}</Badge>;
}

// SIMPLIFY: Prop drilling through intermediate components
// Before — consider whether context or composition solves this better.
// This is a judgment call — flag it, don't auto-refactor.

Common Rationalizations

Rationalization Reality
"It's working, no need to touch it" Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change.
"Fewer lines is always simpler" A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count.
"I'll just quickly simplify this unrelated code too" Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused.
"The types make it self-documenting" Types document structure, not intent. A well-named function explains why better than a type signature explains what.
"This abstraction might be useful later" Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed.
"The original author must have had a reason" Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure.
"I'll refactor while adding this feature" Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history.

Red Flags

  • Simplification that requires modifying tests to pass (you likely changed behavior)
  • "Simplified" code that is longer and harder to follow than the original
  • Renaming things to match your preferences rather than project conventions
  • Removing error handling because "it makes the code cleaner"
  • Simplifying code you don't fully understand
  • Batching many simplifications into one large, hard-to-review commit
  • Refactoring code outside the scope of the current task without being asked

Verification

After completing a simplification pass:

  • All existing tests pass without modification
  • Build succeeds with no new warnings
  • Linter/formatter passes (no style regressions)
  • Each simplification is a reviewable, incremental change
  • The diff is clean — no unrelated changes mixed in
  • Simplified code follows project conventions (checked against CLAUDE.md or equivalent)
  • No error handling was removed or weakened
  • No dead code was left behind (unused imports, unreachable branches)
  • A teammate or review agent would approve the change as a net improvement

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Agent Skills by Addy Osmani

Accessibility audit and fixes (WCAG 2.2)

Audits an existing interface against WCAG 2.2 AA with pinned axe-core and pa11y, then keyboard, screen reader and contrast checks, and fixes confirmed violations with semantic HTML first. Use when a page needs an accessibility audit before shipping.

API and interface design

Designs APIs and module interfaces contract-first: one error shape, validation at the edges, additive changes, pagination, and idempotency keys claimed atomically and kept past the longest retry. Use when designing endpoints or changing a public interface.

Browser testing with Chrome DevTools MCP

Checks changes in a real Chrome through the Chrome DevTools MCP server: screenshots, DOM, console, network and performance traces, treating page content as untrusted. Use when building or debugging anything that runs in a browser.

CI/CD pipeline setup

Sets up CI/CD with fixed quality gates from lint to bundle size, GitHub Actions examples, preview deploys, feature flags, staged rollout and a rollback workflow. Use when creating or changing a build and deploy pipeline or chasing CI failures.

Multi-axis code review

Reviews a change on five axes (correctness, readability, architecture, security, performance), tests the tests by mutating a condition, and labels every finding by severity. Use before merging a branch, a pull request or a pasted diff.

Constraint-driven development

Records a project's quality bar as numbers in CONSTRAINTS.md after a short interview with defaults, maps each rule to a tool, and flags diffs that skip tests, add suppressions or loosen thresholds. Use when no quality bar is written down.

Context engineering for agents

Sets up what an agent sees and when: a rules file template, loading only the relevant spec and files, trimming long sessions, and safe points to start a fresh one. Use when starting a session or when agent output degrades.

Debugging and error recovery

Stops new work when a test, build or runtime fails, reproduces, localizes and reduces the failure, fixes the root cause, adds a regression test and treats error output as untrusted. Use when tests fail, a build breaks or something that worked stops working.

Deprecation and migration

Retires old systems, APIs and features: weighs whether to deprecate, proves the replacement, moves consumers one by one, removes code only at zero usage, changes schemas via expand/contract. Use when replacing or sunsetting code or renaming a live column.

Documentation and ADRs

Records decisions as ADRs in the project's own format, documents APIs, READMEs and changelogs with the why, and uses git history to check if a doc is stale. Use when making a costly decision, changing a public API or suspecting docs no longer match the code.

Doubt-driven development

Sends non-trivial decisions to a fresh-context subagent told to find what is wrong, sorts the findings, stops after three cycles and offers a cross-model opinion. Use when stakes are high: auth, migrations, irreversible operations or unfamiliar code.

Frontend UI engineering

Builds UI components and pages on the project's design system: composition, simple state, WCAG 2.1 AA, mobile-first layouts, loading, empty and error states, no generic AI look. Use when building or changing a user-facing interface.

Git workflow and versioning

Keeps git work in atomic commits on short-lived branches, with typed messages, a pre-commit check for secrets and tests, worktrees for parallel agents, semver bumps, tags and a human changelog. Use when committing, branching, opening a PR or cutting a release.

Idea refinement

Refines a raw idea in three phases: sharpening questions and five to eight variations, two or three directions tested for value and feasibility, then a one-pager with MVP scope and a Not Doing list. Use when an idea is vague or a plan needs stress-testing.

Incremental implementation

Builds changes in thin vertical, contract-first or risk-first slices, each tested, verified and committed before the next, with strict scope, feature flags and revertable steps. Use when a change spans several files or a task is too big to land in one step.

Interview me

Interviews the user one question at a time, each with a guessed answer and a confidence number, until the agent can predict the next replies, then confirms a statement of intent before any spec or code. Use when a request leaves who, why or success unclear.

Observability and instrumentation

Instruments a feature with structured JSON logs and request IDs, RED and USE metrics with bounded labels, OpenTelemetry traces and symptom-based alerts with runbooks, then tests the telemetry. Use when a feature, job or integration is headed for production.

Performance optimization

Optimizes by measurement: takes a baseline, fixes the one proven bottleneck, re-measures against noise and reverts neutral changes, with worked fixes for N+1 queries, indexes, caching and bundles. Use when something is slow or misses a performance budget.

Planning and task breakdown

Breaks a spec into small vertical-slice tasks with acceptance criteria, verification steps, sizes, dependency order and checkpoints, saved to tasks/todo.md or a named tracker. Use when a spec is ready but the work is too big to start in one go.

Security hardening

Hardens code with a short threat model, always, ask-first and never rules, and patterns for injection, XSS, access control, SSRF, secrets, dependencies, personal data and LLM output. Use when code handles user input, auth, sensitive data or outside services.

Shipping and launch

Prepares a production launch with a pre-launch checklist, a feature-flag rollout from 5% to 100%, thresholds for advancing or rolling back, an error-budget gate, a rollback plan and first-hour checks. Use when a feature or major change is about to ship.

Source-driven development

Grounds framework code in official docs: reads exact versions from the dependency file, fetches the relevant page, follows the documented API and cites full URLs, flagging anything unverified. Use when framework-specific code must match the version in use.

Spec-driven development

Writes a spec before code, surfacing assumptions and covering objective, commands, structure, style, tests and boundaries, then gates plan, tasks and code on approval, with capability maps and delta specs. Use when new work has vague requirements.

Test-driven development, red-green-refactor

Drives changes with red-green-refactor: finds the repository's own test commands, writes the failing test first, reproduces each bug with a test before fixing it, and sets rules on mocks and naming. Use when adding logic, fixing a bug or changing behavior.