Code Simplifier
Refactor and simplify recently changed code so it stays readable and maintainable without altering runtime behavior.
Overview
Code Simplifier is an agent skill most often used in Ship (also Build) that applies 47 behavior-preserving rules to clarify and maintain recently modified code.
Install
npx skills add https://github.com/pproenca/dot-skills --skill code-simplifierWhat is this skill?
- 47 prioritized simplification rules grouped across 8 impact-ordered categories
- Four core principles: context first, behavior preservation, scope discipline, clarity over brevity
- Focused on recently modified code with small, reviewable diffs
- Language-idiom guidance for reducing nesting, duplication, and clever one-liners
- Explicit incorrect-vs-correct examples with impact metrics per rule
- 47 rules across 8 categories
- 4 core principles (context, behavior, scope, clarity)
Adoption & trust: 916 installs on skills.sh; 157 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want cleaner, more readable code after a change set, but generic refactors risk hidden behavior changes and huge unrelated diffs.
Who is it for?
Post-implementation cleanup, reducing nesting or duplication in a PR-sized diff, and readability passes before code review.
Skip if: Greenfield architecture rewrites, changing business logic on purpose, or bulk reformatting unrelated legacy files without a scoped change reason.
When should I use this skill?
Simplifying code, reducing complexity, cleaning up recent changes, applying refactoring patterns, or improving readability while preserving exact behavior.
What do I get? / Deliverables
The agent simplifies and names code within a tight scope while preserving exact behavior and aligning with project conventions.
- Smaller, clearer diffs with unchanged behavior
- Refactors aligned to stated project patterns and idioms
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Cleanup and maintainability work sits naturally on the Ship shelf under review-quality, right after implementation and before merge. Subphase review is where simplification, naming, and duplication removal are applied as an explicit quality pass—not ad-hoc edits during coding.
Where it fits
After adding an API handler, run a simplification pass to flatten nesting and rename opaque variables before opening a PR.
Pre-merge cleanup on a diff that grew messy during a solo sprint, using behavior-preservation as a hard constraint.
Touch a hotfix path in production code and simplify only the edited hunk so on-call changes stay easy to audit.
How it compares
Use as a structured simplification playbook instead of open-ended “make this cleaner” chat that may alter semantics.
Common Questions / FAQ
Who is code-simplifier for?
Solo and indie builders using Claude Code, Cursor, or Codex who want agent-driven refactors that stay small, readable, and behavior-identical.
When should I use code-simplifier?
During Ship review after a feature lands, during Build when polishing a module you just edited, or anytime the task is simplify, refactor for clarity, or clean up recent changes—not when you need new features or tests.
Is code-simplifier safe to install?
Treat it like any third-party skill: review the Security Audits panel on this Prism page and skim the 47-rule guidance in SKILL.md before letting an agent touch production paths.
SKILL.md
READMESKILL.md - Code Simplifier
# 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 g