Code Simplify
Inputs
$request: Optional scope or simplification guidance such as a file path, symbol name, or a note like flatten nested conditionals.
Goal
Apply the smallest safe set of readability-focused changes that makes the target code easier to understand and maintain without changing what it does.
Step 0: Resolve scope and suitability
Determine:
- the exact file, symbol, or diff scope to simplify
- whether the user asked for a narrow cleanup or a broader pass
- whether the target is application code, tests, generated code, or a performance-sensitive path
Stop or clarify if:
- the request is too vague to identify the target safely
- the code is generated
- the requested "simplification" is actually a redesign
- the change would obviously alter public behavior or contracts
Use AskUserQuestion only when ambiguity blocks safe progress or when there are multiple legitimate simplification directions.
Success criteria: The simplification scope is explicit and appropriate for a local cleanup workflow.
Step 1: Understand behavior and establish a baseline
Read the real code before editing:
- target file or files
- nearby callers, exports, and adjacent helpers
- existing tests covering the target behavior
Then identify:
- inputs and outputs
- side effects and persistence boundaries
- error handling and guard clauses
- externally visible contracts that must not change
Verification baseline:
- run the narrowest relevant tests, type check, lint target, or build step when feasible
- if no narrow verification exists, state that explicitly and proceed more conservatively
Runtime-specific rule:
- do not mechanically block on rereading
CLAUDE.md every time
- Claude Code already injects the
CLAUDE.md hierarchy into conversation context via getUserContext
- read extra local docs only when the target area has its own conventions or the surrounding code is ambiguous
Success criteria: The current behavior and the verification baseline are clear before edits begin.
Step 2: Identify simplification candidates
Look for changes that reduce local complexity without turning into a redesign:
- flatten deep nesting with guard clauses or early returns
- extract hard-to-read expressions into named variables or helpers
- rename misleading or cryptic local symbols
- eliminate dead code and unused branches
- consolidate obvious duplication
- simplify boolean logic and conditional branching
- reduce parameter sprawl where call sites stay understandable
For each candidate, record:
- location
- category
- risk:
low, medium, or high
- required verification
Load references/simplification-patterns.md for the detailed pattern catalog, anti-patterns, and risk guidance.
Success criteria: A concrete candidate set exists, ordered by risk and expected value.
Step 3: Choose the smallest safe change set
Default behavior:
- apply low-risk and clearly beneficial simplifications directly
- batch related edits by file or tightly coupled call sites
- prefer one small clean pass over a broad "cleanup everything" sweep
Ask the user before proceeding when:
- the best simplification path is not obvious
- the change is medium/high risk
- multiple unrelated cleanup opportunities are present and scope needs a choice
- a rename or extraction crosses a broad public surface
Do not require a ceremonial before/after approval step for trivial, obviously safe cleanups.
Success criteria: The intended edits are limited, justifiable, and proportionate to the user request.
Step 4: Apply the simplifications
Make changes in the safest order:
- dead code removal and trivial boolean cleanup
- flattening and local extraction
- duplication consolidation
- broader renames or small helper extraction
Rules during editing:
- preserve function signatures unless the user explicitly wants broader cleanup
- preserve error handling and observable side effects
- search for references before renaming shared symbols
- if a helper file must be created, keep it adjacent and narrowly scoped
- stop if the cleanup starts cascading into architecture work
Success criteria: The requested simplifications are implemented without unintended scope expansion.
Step 5: Verify behavior is preserved
Rerun the narrowest relevant checks from Step 1:
- targeted tests first
- type check or compile step if relevant
- broader checks only if the touched area requires them
Then confirm:
- the baseline still passes
- no new type or syntax errors were introduced
- the code is actually clearer, not just shorter
If a simplification causes regressions or ambiguous fallout:
- revert the last risky change
- keep the safe improvements
- report the blocked candidate instead of forcing it through
Success criteria: Verification matches or improves on the baseline without behavior changes.
Guardrails
- Do not use this skill proactively for unrelated work.
- Do not add features, comments, or architectural refactors under the label of simplification.
- Do not simplify generated code.
- Do not simplify tests unless the user asked for test cleanup specifically.
- Do not optimize for fewer lines; optimize for lower cognitive load.
- Do not add
disable-model-invocation; the model must be able to invoke this skill when the user explicitly asks for simplification.
- Do not add
context: fork; this workflow edits the current working context and benefits from inline execution.
- Do not add
paths:; this is a generic workflow skill, not a path-activated domain reference.
- Do not keep the full pattern catalog inline in
SKILL.md.
When To Load References
references/simplification-patterns.md
Use for detailed pattern examples, risk guidance, anti-patterns, and escalation heuristics when the target code is non-trivial.
Output Contract
Report:
- resolved scope
- baseline checks run, or explicit verification gap
- simplifications applied by file and category
- verification results
- skipped or deferred opportunities and why
1---
2name: code-simplify
3version: 2.0.0
4description: |
5 Reduce a change's complexity WITHOUT altering behavior — lower cognitive load, not line count: read
6 the target plus its callers and tests, take a baseline check, then apply the smallest clarifying edits
7 in safest order (dead code and boolean cleanup → flatten nesting with guard clauses → consolidate
8 duplication → local renames and helper extraction), respecting Chesterton's Fence. Re-runs the
9 baseline after each edit and reverts any change that alters observable behavior or regresses, keeping
10 only the safe improvements — a simplification that changes semantics is a bug, not a cleanup. Use only
11 when the user explicitly asks to simplify or clean up existing code.
12allowed-tools:
13 - Read
14 - Edit
15 - Write
16 - Bash
17 - Glob
18 - Grep
19 - AskUserQuestion
20argument-hint: "[scope or simplification goal]"
21arguments:
22 - request
23when_to_use: |
24 Use only when the user explicitly asks to simplify or clean up existing code. Examples:
25 "simplify this", "clean up this file", "reduce complexity here", or "/code-simplify auth.ts".
26 Do NOT run it proactively during unrelated work, and do NOT use it to change behavior or fix defects
27 (that's bugfix), tune speed, redesign architecture, or touch generated code — those alter what the
28 code does; simplification must not.
29metadata:
30 source: https://skillmd.com/skills/ulpi-io/code-simplify
31---
32
33<EXTREMELY-IMPORTANT>
34This skill edits code. Non-negotiable rules:
351. Read the target code, nearby callers, and relevant tests before changing anything.
362. Establish the narrowest useful baseline check before edits when feasible.
373. Preserve behavior, side effects, and error handling.
384. Ask the user only when the scope is ambiguous, the simplification is risky, or there are real alternatives.
395. Keep the invocation body focused on the simplification loop; load detailed patterns from references only when needed.
40</EXTREMELY-IMPORTANT>
41
42# Code Simplify
43
44## Inputs
45
46- `$request`: Optional scope or simplification guidance such as a file path, symbol name, or a note like `flatten nested conditionals`.
47
48## Goal
49
50Apply the smallest safe set of readability-focused changes that makes the target code easier to understand and maintain without changing what it does.
51
52## Step 0: Resolve scope and suitability
53
54Determine:
55
56- the exact file, symbol, or diff scope to simplify
57- whether the user asked for a narrow cleanup or a broader pass
58- whether the target is application code, tests, generated code, or a performance-sensitive path
59
60Stop or clarify if:
61
62- the request is too vague to identify the target safely
63- the code is generated
64- the requested "simplification" is actually a redesign
65- the change would obviously alter public behavior or contracts
66
67Use `AskUserQuestion` only when ambiguity blocks safe progress or when there are multiple legitimate simplification directions.
68
69**Success criteria**: The simplification scope is explicit and appropriate for a local cleanup workflow.
70
71## Step 1: Understand behavior and establish a baseline
72
73Read the real code before editing:
74
75- target file or files
76- nearby callers, exports, and adjacent helpers
77- existing tests covering the target behavior
78
79Then identify:
80
81- inputs and outputs
82- side effects and persistence boundaries
83- error handling and guard clauses
84- externally visible contracts that must not change
85
86Verification baseline:
87
88- run the narrowest relevant tests, type check, lint target, or build step when feasible
89- if no narrow verification exists, state that explicitly and proceed more conservatively
90
91Runtime-specific rule:
92
93- do not mechanically block on rereading `CLAUDE.md` every time
94- Claude Code already injects the `CLAUDE.md` hierarchy into conversation context via `getUserContext`
95- read extra local docs only when the target area has its own conventions or the surrounding code is ambiguous
96
97**Success criteria**: The current behavior and the verification baseline are clear before edits begin.
98
99## Step 2: Identify simplification candidates
100
101Look for changes that reduce local complexity without turning into a redesign:
102
103- flatten deep nesting with guard clauses or early returns
104- extract hard-to-read expressions into named variables or helpers
105- rename misleading or cryptic local symbols
106- eliminate dead code and unused branches
107- consolidate obvious duplication
108- simplify boolean logic and conditional branching
109- reduce parameter sprawl where call sites stay understandable
110
111For each candidate, record:
112
113- location
114- category
115- risk: `low`, `medium`, or `high`
116- required verification
117
118Load `references/simplification-patterns.md` for the detailed pattern catalog, anti-patterns, and risk guidance.
119
120**Success criteria**: A concrete candidate set exists, ordered by risk and expected value.
121
122## Step 3: Choose the smallest safe change set
123
124Default behavior:
125
126- apply low-risk and clearly beneficial simplifications directly
127- batch related edits by file or tightly coupled call sites
128- prefer one small clean pass over a broad "cleanup everything" sweep
129
130Ask the user before proceeding when:
131
132- the best simplification path is not obvious
133- the change is medium/high risk
134- multiple unrelated cleanup opportunities are present and scope needs a choice
135- a rename or extraction crosses a broad public surface
136
137Do not require a ceremonial before/after approval step for trivial, obviously safe cleanups.
138
139**Success criteria**: The intended edits are limited, justifiable, and proportionate to the user request.
140
141## Step 4: Apply the simplifications
142
143Make changes in the safest order:
144
1451. dead code removal and trivial boolean cleanup
1462. flattening and local extraction
1473. duplication consolidation
1484. broader renames or small helper extraction
149
150Rules during editing:
151
152- preserve function signatures unless the user explicitly wants broader cleanup
153- preserve error handling and observable side effects
154- search for references before renaming shared symbols
155- if a helper file must be created, keep it adjacent and narrowly scoped
156- stop if the cleanup starts cascading into architecture work
157
158**Success criteria**: The requested simplifications are implemented without unintended scope expansion.
159
160## Step 5: Verify behavior is preserved
161
162Rerun the narrowest relevant checks from Step 1:
163
164- targeted tests first
165- type check or compile step if relevant
166- broader checks only if the touched area requires them
167
168Then confirm:
169
170- the baseline still passes
171- no new type or syntax errors were introduced
172- the code is actually clearer, not just shorter
173
174If a simplification causes regressions or ambiguous fallout:
175
176- revert the last risky change
177- keep the safe improvements
178- report the blocked candidate instead of forcing it through
179
180**Success criteria**: Verification matches or improves on the baseline without behavior changes.
181
182## Guardrails
183
184- Do not use this skill proactively for unrelated work.
185- Do not add features, comments, or architectural refactors under the label of simplification.
186- Do not simplify generated code.
187- Do not simplify tests unless the user asked for test cleanup specifically.
188- Do not optimize for fewer lines; optimize for lower cognitive load.
189- Do not add `disable-model-invocation`; the model must be able to invoke this skill when the user explicitly asks for simplification.
190- Do not add `context: fork`; this workflow edits the current working context and benefits from inline execution.
191- Do not add `paths:`; this is a generic workflow skill, not a path-activated domain reference.
192- Do not keep the full pattern catalog inline in `SKILL.md`.
193
194## When To Load References
195
196- `references/simplification-patterns.md`
197 Use for detailed pattern examples, risk guidance, anti-patterns, and escalation heuristics when the target code is non-trivial.
198
199## Output Contract
200
201Report:
202
2031. resolved scope
2042. baseline checks run, or explicit verification gap
2053. simplifications applied by file and category
2064. verification results
2075. skipped or deferred opportunities and why