code-simplification

Name: code-simplification
Author: addyosmani

14kinstalls8.6kforks

How to install code-simplification?

addyosmani/agent-skills/code-simplification

$npx -y skills add addyosmani/agent-skills --skill code-simplification

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Code Simplification
2
3	> Inspired by the [Claude Code Simplifier plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md). Adapted here as a model-agnostic, process-driven skill for any AI coding agent.
4
5	## Overview
6
7	Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
8
9	## When to Use
10
11	- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
12	- During code review when readability or complexity issues are flagged
13	- When you encounter deeply nested logic, long functions, or unclear names
14	- When refactoring code written under time pressure
15	- When consolidating related logic scattered across files
16	- After merging changes that introduced duplication or inconsistency
17
18	When NOT to use:
19
20	- Code is already clean and readable — don't simplify for the sake of it
21	- You don't understand what the code does yet — comprehend before you simplify
22	- The code is performance-critical and the "simpler" version would be measurably slower
23	- You're about to rewrite the module entirely — simplifying throwaway code wastes effort
24
25	## The Five Principles
26
27	### 1. Preserve Behavior Exactly
28
29	Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
30
31	```
32	ASK BEFORE EVERY CHANGE:
33	→ Does this produce the same output for every input?
34	→ Does this maintain the same error behavior?
35	→ Does this preserve the same side effects and ordering?
36	→ Do all existing tests still pass without modification?
37	```
38
39	### 2. Follow Project Conventions
40
41	Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:
42
43	```
44	1. Read CLAUDE.md / project conventions
45	2. Study how neighboring code handles similar patterns
46	3. Match the project's style for:
47	- Import ordering and module system
48	- Function declaration style
49	- Naming conventions
50	- Error handling patterns
51	- Type annotation depth
52	```
53
54	Simplification that breaks project consistency is not simplification — it's churn.
55
56	### 3. Prefer Clarity Over Cleverness
57
58	Explicit code is better than compact code when the compact version requires a mental pause to parse.
59
60	```typescript
61	// UNCLEAR: Dense ternary chain
62	const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';
63
64	// CLEAR: Readable mapping
65	function getStatusLabel(item: Item): string {
66	if (item.isNew) return 'New';
67	if (item.isUpdated) return 'Updated';
68	if (item.isArchived) return 'Archived';
69	return 'Active';
70	}
71	```
72
73	```typescript
74	// UNCLEAR: Chained reduces with inline logic
75	const result = items.reduce((acc, item) => ({
76	...acc,
77	[item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
78	}), {});
79
80	// CLEAR: Named intermediate step
81	const countById = new Map<string, number>();
82	for (const item of items) {
83	countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
84	}
85	```
86
87	### 4. Maintain Balance
88
89	Simplification has a failure mode: over-simplification. Watch for these traps:
90
91	- Inlining too aggressively — removing a helper that gave a concept a name makes the call site harder to read
92	- Combining unrelated logic — two simple functions merged into one complex function is not simpler
93	- Removing "unnecessary" abstraction — some abstractions exist for extensibility or testability, not complexity
94	- Optimizing for line count — fewer lines is not the goal; easier comprehension is
95
96	### 5. Scope to What Changed
97
98	Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.
99
100	## The Simplification Process
101
102	### Step 1: Understand Before Touching (Chesterton's Fence)
103
104	Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.
105
106	```
107	BEFORE SIMPLIFYING, ANSWER:
108	- What is this code's responsibility?
109	- What calls it? What does it call?
110	- What are the edge cases and error paths?
111	- Are there tests that define the expected behavior?
112	- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
113	- Check git

People who liked this also viewed

6 picks

Type

code-simplification

14kinstalls8.6kforks

View on GitHub

How to install code-simplification?

addyosmani/agent-skills/code-simplification

$npx -y skills add addyosmani/agent-skills --skill code-simplification

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Code Simplification
2
3	> Inspired by the [Claude Code Simplifier plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md). Adapted here as a model-agnostic, process-driven skill for any AI coding agent.
4
5	## Overview
6
7	Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
8
9	## When to Use
10
11	- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
12	- During code review when readability or complexity issues are flagged
13	- When you encounter deeply nested logic, long functions, or unclear names
14	- When refactoring code written under time pressure
15	- When consolidating related logic scattered across files
16	- After merging changes that introduced duplication or inconsistency
17
18	When NOT to use:
19
20	- Code is already clean and readable — don't simplify for the sake of it
21	- You don't understand what the code does yet — comprehend before you simplify
22	- The code is performance-critical and the "simpler" version would be measurably slower
23	- You're about to rewrite the module entirely — simplifying throwaway code wastes effort
24
25	## The Five Principles
26
27	### 1. Preserve Behavior Exactly
28
29	Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
30
31	```
32	ASK BEFORE EVERY CHANGE:
33	→ Does this produce the same output for every input?
34	→ Does this maintain the same error behavior?
35	→ Does this preserve the same side effects and ordering?
36	→ Do all existing tests still pass without modification?
37	```
38
39	### 2. Follow Project Conventions
40
41	Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:
42
43	```
44	1. Read CLAUDE.md / project conventions
45	2. Study how neighboring code handles similar patterns
46	3. Match the project's style for:
47	- Import ordering and module system
48	- Function declaration style
49	- Naming conventions
50	- Error handling patterns
51	- Type annotation depth
52	```
53
54	Simplification that breaks project consistency is not simplification — it's churn.
55
56	### 3. Prefer Clarity Over Cleverness
57
58	Explicit code is better than compact code when the compact version requires a mental pause to parse.
59
60	```typescript
61	// UNCLEAR: Dense ternary chain
62	const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';
63
64	// CLEAR: Readable mapping
65	function getStatusLabel(item: Item): string {
66	if (item.isNew) return 'New';
67	if (item.isUpdated) return 'Updated';
68	if (item.isArchived) return 'Archived';
69	return 'Active';
70	}
71	```
72
73	```typescript
74	// UNCLEAR: Chained reduces with inline logic
75	const result = items.reduce((acc, item) => ({
76	...acc,
77	[item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
78	}), {});
79
80	// CLEAR: Named intermediate step
81	const countById = new Map<string, number>();
82	for (const item of items) {
83	countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
84	}
85	```
86
87	### 4. Maintain Balance
88
89	Simplification has a failure mode: over-simplification. Watch for these traps:
90
91	- Inlining too aggressively — removing a helper that gave a concept a name makes the call site harder to read
92	- Combining unrelated logic — two simple functions merged into one complex function is not simpler
93	- Removing "unnecessary" abstraction — some abstractions exist for extensibility or testability, not complexity
94	- Optimizing for line count — fewer lines is not the goal; easier comprehension is
95
96	### 5. Scope to What Changed
97
98	Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.
99
100	## The Simplification Process
101
102	### Step 1: Understand Before Touching (Chesterton's Fence)
103
104	Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.
105
106	```
107	BEFORE SIMPLIFYING, ANSWER:
108	- What is this code's responsibility?
109	- What calls it? What does it call?
110	- What are the edge cases and error paths?
111	- Are there tests that define the expected behavior?
112	- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
113	- Check git

People who liked this also viewed

6 picks

Type