Code simplification skill: Addy Osmani's behavior-preserving cleanup for agents

Source: addyosmani/agent-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 24 October 2026

What is the code-simplification skill?

code-simplification is a code simplification skill that makes a coding agent reduce complexity in working code while keeping its behavior exactly the same. It changes how code reads, not what it does, and checks every step against your tests.

It is one of 25 skills in addyosmani/agent-skills, Addy Osmani's pack that maps skills to a lifecycle of define, plan, build, verify, review and ship. The README lists it under Review with the summary "Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior."

The SKILL.md credits its origin: it is "Inspired by the Claude Code Simplifier plugin. Adapted here as a model-agnostic, process-driven skill for any AI coding agent."

Its description reads: "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."

Its skills.sh page listed 61.6K installs (snapshot, 24 October 2026).

What does it do?

The test for every change is one question: "Would a new team member understand this faster than the original?" The SKILL.md, about 13.5 KB, builds on five principles:

1. Preserve behavior exactly. Same outputs, errors, side effects and ordering, and existing tests pass unmodified. "If you're not sure a simplification preserves behavior, don't make it."
2. Follow project conventions. Read CLAUDE.md and neighboring code first. The skill calls simplification that breaks consistency churn, not simplification.
3. Prefer clarity over cleverness. A nested ternary becomes a short function with early returns; a dense reduce becomes a named Map loop.
4. Maintain balance. It warns against inlining helpers that named a concept, merging unrelated functions, and optimizing for line count.
5. Scope to what changed. Default to recently modified code and avoid drive-by refactors.

Then comes a four-step process:

• Understand before touching. This is Chesterton's Fence: find out why code exists before removing it. The agent answers what the code does, what calls it, its edge cases, which tests define it, and checks git blame for context.
• Identify opportunities. Three tables list concrete signals: deep nesting (3+ levels), long functions (50+ lines), nested ternaries, boolean flag parameters, generic or misleading names, duplicated logic, dead code, wrappers that add nothing, and patterns like "strategy-with-one-strategy".
• Apply changes incrementally. One simplification, run the tests, commit if green, revert if red. Refactors go in a separate PR from feature or bug fix work. The Rule of 500 says to use codemods or AST transforms for anything over 500 lines.
• Verify the result. Compare before and after, and revert if the "simplified" version is harder to read.

Language sections show before and after examples for TypeScript, Python and React. The skill closes with rationalizations, red flags such as removing error handling because "it makes the code cleaner", and a nine-item verification checklist.

How do you install it?

Just this skill. The skills.sh command, using the open skills CLI:

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

Add -g to install for all projects. In Claude Code it lands in .claude/skills/code-simplification/ or ~/.claude/skills/code-simplification/, per the skills docs. The README notes a per-skill install "copies only skills/<name>/, not the repo-level references/ directory." This skill doesn't link into references/, so nothing breaks.

The whole pack in Claude Code. From the README:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

This adds the /code-simplify command, which invokes the skill, targets recently changed code unless you name a scope, and ends by suggesting code-review-and-quality to review the result. If the marketplace add fails over SSH, use /plugin marketplace add https://github.com/addyosmani/agent-skills.git.

Codex. Run codex plugin marketplace add addyosmani/agent-skills, then codex plugin add agent-skills@agent-skills (Codex CLI v0.122 or later), and call @code-simplification. See Codex skills and Cursor skills for other setups.

claude.ai. Zip the folder and upload it under Customize, then Skills, following the Claude Help Center.

How do you use it?

Run it after a feature works and tests pass. Give it a scope, because the skill defaults to recent changes and avoids touching code you didn't name.

Example prompts (suggestions, not quotes from the repo):

• Simplify the code I changed on this branch. Keep behavior identical and run the tests after each change.
• src/billing/invoice.ts has four levels of nesting. Simplify it with guard clauses, one commit per change.
• Find dead code and pass-through wrappers in src/lib. List them before you delete anything.
• This rename touches about 800 lines. Write a codemod for it instead of editing by hand.
• Review this function for clarity. If a simpler version isn't clearly easier to read, leave it alone.

You need a working test suite. Without one, the skill has no way to show behavior was preserved, so write tests first.

How does it compare with other simplification options?

The Claude Code commands reference says /simplify "doesn't look for correctness bugs" and points to /code-review for that.

Tips and limits

• Tests are the contract. The whole method depends on a suite that covers the code. Thin coverage means "preserved behavior" is a guess.
• Readability is a judgment call. Some examples, such as replacing an if/else with ||, are style choices. Principle 2 says your project's conventions win.
• Don't mix it with features. The skill wants refactors in their own PR. If you ask it to simplify while building, expect it to push back.
• Security audit. On 24 October 2026 the skills.sh page showed Gen Agent Trust Hub: Pass, Socket: Pass, Snyk: Pass. The folder holds only SKILL.md; test runs and git blame go through your agent's shell under your permission settings.

The repo is MIT licensed, so you can copy and edit the skill if you keep the copyright notice.

Save it in your Kipt library

If you want a version tuned to your stack, say with your own thresholds instead of 3 nesting levels and 50-line functions, keep it in Kipt. Open Skills and paste the GitHub folder link, or drop in a folder or .zip; a repo with many skills shows a list to pick from. Kipt keeps skills in your own private GitHub repo and installs all of them into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Addy Osmani or addyosmani/agent-skills.

Similar skills

• Code review and quality skill: Addy Osmani's five-axis review, the suggested next step after simplifying.
• Improve codebase architecture skill: Matt Pocock's repo-wide scan for refactor candidates.
• Codebase design skill: a shared vocabulary for deep modules and interfaces.
• Incremental implementation skill: the same one-change-at-a-time discipline, applied to new features.
• Refactoring prompts: reusable prompts for one-off cleanups.