lgbarn/shipyard/code-simplification
Claude Code and agent skill by lgbarn/shipyard
- community
Checking that the SKILL.md file is still in the repository.
Finds and removes duplication, dead code, over-engineering, and AI-generated bloat such as verbose error handling and redundant type checks. Use after implementing features, before claiming a phase is complete, when reviewing AI-generated code, or when code feels overly complex. Also use when a pattern repeats across files, a function exceeds 40 lines, nesting exceeds 3 levels, or an abstraction has only one implementation.
Install
npx vskill@latest install lgbarn/shipyard/code-simplificationSKILL.md
Code Simplification
<activation>
When This Skill Activates
- After all tasks in a phase are complete (before shipping)
- When reviewing code generated by multiple builder agents
- When a file has been touched by 3+ different tasks
- When you notice patterns repeating across files
- Before claiming a phase is production-ready
The simplifier agent references this skill for systematic cross-task analysis.
Natural Language Triggers
- "simplify this", "clean up", "too complex", "reduce complexity", "this is bloated"
</activation>
Overview
AI-generated code accumulates complexity. Each task is implemented in isolation by a fresh agent that can't see the full picture. After multiple tasks, duplication creeps in, abstractions multiply, and dead code lingers.
Core principle: The simplest code that works correctly is the best code. Complexity is a cost, not a feature.
This skill applies after implementation, not during. Don't prematurely optimize -- but don't ship bloat either.
<instructions>
Simplification Process
When reviewing code for simplification:
- Identify scope: What files changed in this phase? (Use git diff)
- Scan for duplication: Look for similar patterns across files
- Check complexity: Flag functions exceeding thresholds
- Find dead code: Look for unused definitions
- Spot over-engineering: Look for abstractions with single implementations
- Check AI patterns: Apply the AI anti-pattern checklist
- Prioritize findings:
- High: Clear duplication (3+), dead code, obvious bloat
- Medium: Complexity reduction, near-duplicates
- Low: Style consistency, minor simplifications
Duplication Detection
What to Look For
Exact duplicates: Identical code blocks in different files or functions.
Near duplicates: Same structure, different details.
Parallel hierarchies: When adding a new type requires changes in multiple places.
Copy-paste config: Same configuration blocks repeated in Docker, Terraform, or CI files.
The Rule of Three
- 2 occurrences: Note it, but don't extract yet.
- 3 occurrences: Extract. The pattern is real.
- 1 abstraction serving 1 caller: Inline it. The abstraction has no value.
Complexity Reduction
Techniques
Extract method: When a function does too many things.
Early returns / guard clauses: Eliminate deep nesting.
Replace conditionals with polymorphism: When type-checking drives behavior.
Simplify boolean expressions: Collapse nested boolean logic.
Complexity Thresholds
| Metric | Acceptable | Review | Refactor | |
|---|---|---|---|---|
| Function length | < 20 lines | 20-40 lines | > 40 lines | |
| Nesting depth | <= 2 levels | 3 levels | > 3 levels | |
| Parameters | <= 3 | 4-5 | > 5 | |
| Cyclomatic complexity | <= 5 | 6-10 | > 10 |
Dead Code Identification
What Counts as Dead Code
- Unused imports -- imported but never referenced
- Unused variables -- assigned but never read
- Unreachable branches -- conditions that can never be true
- Commented-out code -- if it's needed, it's in git history
- Unused functions/methods -- defined but never called
- Vestigial parameters -- accepted but never used
- Feature flags for shipped features -- the flag is always on
What Does NOT Count
- Public API surface -- may have external callers
- Test utilities -- called only from tests
- Interface implementations -- required by contract
- Error handlers for rare conditions -- needed for robustness
Over-Engineering Indicators
Premature Abstraction
Rule: If there's only one implementation, don't create an abstraction. Add it when the second implementation arrives.
Unnecessary Indirection
Configuration for One Value
Rule: Make it configurable when a second consumer needs a different value, not before.
AI-Specific Anti-Patterns
AI code generators commonly produce these patterns. Watch for them:
Verbose Error Handling
Redundant Type Checks
Over-Defensive Coding
Unnecessary Wrapper Functions
Shell/Bash AI Anti-Patterns
</instructions>
<examples>
Example: Full Simplification Finding
<example type="good" title="Identifying and resolving cross-agent duplication"> Context: Three builder agents each implemented a task touching API endpoints. Each added its own request validation helper.
Finding: Three near-identical validate_request_body() functions in routes/users.py, routes/projects.py, and routes/teams.py.
Before (in each file):
After (extracted to shared module):
Priority: High -- 3 exact duplicates, Rule of Three applies. </example>
</examples>
<rules>
Red Flags -- STOP and Simplify
- Same logic in 3+ places
- Function > 40 lines
- Nesting > 3 levels
- Abstract class with one concrete implementation
- Wrapper that just delegates
- Config for a value used in one place
- Try/except that re-raises the same exception
- Type check for a statically typed parameter
- Null check after a function that can't return null
- Commented-out code blocks
Common Rationalizations
| Excuse | Reality | |
|---|---|---|
| "We might need it later" | YAGNI. Add it when you need it. | |
| "It's more extensible" | Extensibility without use cases is waste. | |
| "The abstraction makes it cleaner" | One caller = inline is cleaner. | |
| "Deleting code feels risky" | Git remembers. Dead code is maintenance cost. | |
| "It's just a few extra lines" | Lines compound. 10 files x 5 extra lines = 50 lines of noise. | |
| "The AI generated it, it must be right" | AI optimizes for completeness, not simplicity. | |
| "Refactoring might break things" | Tests exist. If they don't, add them first. |
</rules>
Integration
Referenced by:
- shipyard:simplifier -- Uses this skill as the analysis framework for cross-task simplification
- shipyard:reviewer -- Code quality review (Stage 2) checks for complexity
Pairs with:
- shipyard:shipyard-tdd -- Tests make simplification safe
- shipyard:shipyard-verification -- Simplification claims need evidence
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/code-simplification/SKILL.md
Popularity
- Repository stars
- 47
- 7-day trend score
- 19
Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 22 Mar 2026, 7 months ago.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/lgbarn/shipyard/code-simplification)