Code Simplification skill for Claude Code: cleaner code, same behavior

Makes your agent simplify working code for readability without changing what it does, one small change at a time.

Installs: 67.6K; on skills.sh
Stars: 112.6K; on GitHub
Updated: Nov 2026; last repo commit

code-simplification makes the agent reduce complexity in code that already works, while keeping its behavior exactly the same. It loads when you ask to simplify, clean up or reduce nesting, even for code pasted inline, and it works in steps: understand the code first, spot specific patterns, change one thing at a time and run the tests after each change.

It reads your project conventions (CLAUDE.md or similar) before it edits, so it follows your style instead of its own. It needs a test suite to check against and bundles no scripts. The SKILL.md says it is inspired by the Claude Code Simplifier plugin and adapted as a model-agnostic, process-driven skill.

Good for

Developers with code that works but is hard to read
Reviewers dealing with deep nesting, long functions or duplication
Teams cleaning up code written under time pressure

Install code-simplification

Claude Code

Copy this prompt.

Install the code-simplification skill in Claude Code. Run this command:

npx skills add https://github.com/addyosmani/agent-skills --skill code-simplification

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity. Use when asked to simplify, clean up, or reduce the nesting of a function or module that already works, even when the code is pasted inline and nothing else needs to change.

Sections in SKILL.md

Overview
When to Use
The Five Principles
1. Preserve Behavior Exactly
2. Follow Project Conventions
3. Prefer Clarity Over Cleverness
4. Maintain Balance
5. Scope to What Changed
The Simplification Process
Step 1: Understand Before Touching (Chesterton's Fence)
Step 2: Identify Simplification Opportunities
Step 3: Apply Changes Incrementally
Step 4: Verify the Result
Language-Specific Guidance
TypeScript / JavaScript
Python

Key facts

Author: addyosmani (repo owner)
Installs on skills.sh: 67,601 (Nov 2, 2026)
GitHub stars: 112,555 on the agent-skills repo (Nov 2, 2026)
License: MIT
Last commit: 2026-11-01
What installs: 1 file: SKILL.md
Needs: A test suite to run after each change
Works in: Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode and more, per the README

What it includes

Every change must keep inputs, outputs, side effects and errors identical
The first of five principles. If the agent is not sure a change keeps behavior, it should not make it.
Preserve behavior exactly
Reads CLAUDE.md and neighboring code, then matches your style
Simplification should make code more consistent with your codebase, not impose outside preferences.
Read · Follow project conventions
Applies Chesterton's Fence: learn why code exists before removing it
Before changing anything, the agent answers what the code is for, who calls it, what the edge cases are and why it was written that way.
Read · Understand before touching
Scans for nesting, long functions, vague names, dead code and duplication
Three tables list concrete signals (structure, naming, redundancy) and the fix for each.
Spot simplification patterns
One change, then the tests; commit if they pass, revert if they fail
Refactors go in separate changes from features. Over 500 lines, it suggests codemods or AST transforms over hand edits (Rule of 500).
Runs code · Apply changes incrementally
Compares before and after and checks the diff is clean and reviewable
If the simplified version is harder to understand, the agent reverts it.
Verify the result
Before and after examples for TypeScript/JavaScript, Python and React
Short examples such as guard clauses, filter over manual loops and removing needless async wrappers.
Language guidance

From the official docs

Permissions

Low risk

It edits your files and runs your tests, so a bad change could land in your working tree. Work on a branch and review the diff.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It edits your code and may commit
Step 3 says to commit when tests pass and revert when they fail. Work on a branch and review the diff before you merge.
It runs your test suite after each change
The tests run in your project with your own settings. A slow suite makes each step slow.

Questions

What does code-simplification do?

It makes Claude simplify code that already works so it is easier to read and change, without altering behavior. It works on recently changed code by default and avoids drive-by refactors of unrelated files.

How do I install code-simplification?

Use the install box above. The README also lists npx skills add addyosmani/agent-skills --skill code-simplification for one skill, and a Claude Code plugin for the whole pack (/plugin marketplace add addyosmani/agent-skills, then /plugin install agent-skills@addy-agent-skills). A one-skill install copies only skills/code-simplification/ and not the repo-level references folder; the README says the skill still works.

Will it change what my code does?

The skill's first rule is to preserve behavior exactly, and its red flags say that having to edit tests to make them pass means behavior probably changed. Run your own tests and review the diff anyway.

How is it different from the Claude Code Simplifier plugin?

The SKILL.md says it is inspired by that plugin and adapted as a model-agnostic, process-driven skill for any AI coding agent.

Is it safe to run?

It is a text file of instructions and bundles no scripts. It tells the agent to edit your code, run your tests and commit or revert, so check the diff and use a clean git branch.

Does it work in Codex, Cursor or other tools?

The README documents Codex (codex plugin marketplace add addyosmani/agent-skills, then codex plugin add agent-skills@agent-skills, Codex CLI v0.122 or newer), Cursor (copy skills into .cursor/skills/), Gemini CLI, Windsurf, OpenCode, GitHub Copilot, Kiro and others. It says the skills are plain Markdown that work with any agent that accepts instruction files. It does not mention the Claude app.

Information

updated Nov 2, 2026

Repository: addyosmani/agent-skills
Folder: skills/code-simplification

addyosmani/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

code-simplification SKILL.md · github.com
addyosmani/agent-skills README · github.com