Code Simplify
Refactor recently touched or scoped files for clarity and lower complexity without changing behavior or public APIs.
Overview
Code Simplify is an agent skill most often used in Ship (also Build) that refactors scoped code for clarity and lower complexity while preserving behavior, public contracts, and side effects.
Install
npx skills add https://github.com/paulrberg/agent-skills --skill code-simplifyWhat is this skill?
- Resolves scope via git: user paths, commit range, fenced Resolved scope, or session-modified files only
- Optional --no-verify and --no-report for orchestrated parent workflows
- Requires a git repository (git rev-parse --git-dir) or stops with clear guidance
- Preserves behavior, public contracts, and side effects while favoring explicit local clarity
- Default path verifies touched behavior and delivers a full user-facing report
- Two CLI flags: --no-verify and --no-report for orchestrated runs
Adoption & trust: 2.1k installs on skills.sh; 62 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You shipped or edited code that works but is hard to read, over-clever, or costly to maintain, and you want a safe simplification pass with optional verification.
Who is it for?
Solo builders cleaning up session edits or a named diff before PR, with git available and tests or verification the agent can run.
Skip if: Non-git folders, wholesale rewrites without a defined scope, or cases where you need semantic redesign rather than clarity-preserving simplification.
When should I use this skill?
User asks to simplify code, clean up code, refactor for clarity, reduce complexity, improve readability, make code easier to maintain, or simplify recently modified code.
What do I get? / Deliverables
Scoped files are simplified with explicit structure, optional behavioral verification runs, and you get a concise or full report depending on flags—ready for commit or parent orchestrator handoff.
- Simplified source in scoped files
- Optional verification results
- Full or minimal report per flags
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship because the skill defaults to verifying behavior and reporting after edits—best aligned with pre-merge review and cleanup. Review subphase fits readability, complexity reduction, and contract-preserving simplification before code lands.
Where it fits
Flatten nested service logic after a spike while keeping HTTP handlers and types unchanged.
Run a clarity pass on session-modified files before opening a PR.
Simplify a hotfix branch’s touched files with --no-report when a parent agent owns final verification.
How it compares
Use for behavior-preserving readability refactors instead of ad-hoc “make this prettier” chat without git scope or verification.
Common Questions / FAQ
Who is code-simplify for?
Indie developers and small teams using Claude Code, Cursor, or similar agents who want structured simplification on a git-scoped set of files.
When should I use code-simplify?
During Build after a messy implementation pass, during Ship before review or merge, or whenever you ask to simplify, clean up, refactor for clarity, or reduce complexity on recently modified code.
Is code-simplify safe to install?
Review the Security Audits panel on this Prism page and treat it like any skill that runs git and shell in your repo—use scoped paths and read changes before merging.
SKILL.md
READMESKILL.md - Code Simplify
# Code Simplify ## Objective Simplify code while preserving behavior, public contracts, and side effects. Favor explicit code and local clarity over clever or compressed constructs. ## Arguments - `--no-verify`: Skip verification because a parent orchestrator will verify the final result separately. - `--no-report`: Skip the full user-facing report. Keep only concise working notes needed by the caller. - Default: verify touched behavior and present the full report. ## Scope Resolution 1. Verify repository context: `git rev-parse --git-dir`. If this fails, stop and tell the user to run from a git repository. 2. If user provides file paths/patterns, a commit/range, or a `Resolved scope` fenced block with one repo-relative path per line, scope is exactly those targets. 3. Otherwise, scope is **only** session-modified files. Do not include other uncommitted changes. 4. If there are no session-modified files, fall back to all uncommitted tracked + untracked files: - tracked: `git diff --name-only --diff-filter=ACMR` - untracked: `git ls-files --others --exclude-standard` - combine both lists and de-duplicate. 5. Exclude generated/low-signal files unless requested: lockfiles, minified bundles, build outputs, vendored code. 6. If scope still resolves to zero files, report and stop. ## Operating Rules - Preserve runtime behavior exactly. Keep inputs, outputs, side effects, and error behavior stable. - Prefer project conventions over personal preferences. Infer conventions from existing code, linters, formatters, and tests. - Limit scope to user-requested files or recently modified code unless explicitly asked to broaden. - Make small, reversible edits. Avoid broad rewrites when targeted simplifications solve the problem. - Call out uncertainty immediately when behavior may change. ## Workflow ### 1) Determine Scope - Resolve target files using the "Scope Resolution" section above. ### 2) Build a Behavior Baseline - Read surrounding context, not only changed lines. - Identify invariants that must not change: - function signatures and exported APIs - state transitions and side effects - persistence/network behavior - user-facing messages and error semantics where externally relied on - Note available verification commands (lint, tests, typecheck). ### 3) Apply Simplification Passes (in this order) 1. Control flow: - Flatten deep nesting with guard clauses and early returns. - Replace nested ternaries with clearer conditionals. 2. Naming and intent: - Rename ambiguous identifiers when local context supports safe renaming. - Separate mixed concerns into small helpers with intent-revealing names. 3. Duplication: - Remove obvious duplication. - Abstract only when at least two real call sites benefit and the abstraction reduces cognitive load. 4. Data shaping: - Break dense transform chains into named intermediate steps when readability improves. - Keep hot-path performance characteristics stable unless improvement is explicit and measured. 5. Type and contract clarity: - Add or tighten type annotations when they improve readability and safety without forcing broad churn. - Preserve external interfaces unless asked to change them. ### 4) Enforce Safety Constraints - Do not convert sync APIs to async (or reverse) unless explicitly requested. - Do not alter error propagation strategy unless behavior remains equivalent and verified. - Do not remove logging, telemetry, guards, or retries that encode operational intent. - Do not collapse domain-specific steps into generic helpers that hide intent. ### 5) Verify Skip this s