code-simplification
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.
55
61%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/code-simplification/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description has strong completeness with multiple explicit 'Use when' clauses that clearly communicate both purpose and trigger conditions. However, it lacks specificity in the concrete actions it performs (only 'simplifies code') and could benefit from more natural trigger terms users would actually say. The distinctiveness is moderate, as it could overlap with general code review or refactoring skills.
Suggestions
Add specific concrete actions like 'Extracts helper functions, reduces nesting depth, removes dead code, simplifies conditionals, and improves naming conventions'.
Include more natural trigger terms users would say, such as 'clean up code', 'messy code', 'hard to read', 'technical debt', 'spaghetti code', or 'code smell'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (code refactoring) and a general action ('simplifies code for clarity'), but does not list multiple specific concrete actions like 'extract methods, reduce nesting, rename variables, remove dead code'. The action is singular and somewhat vague. | 2 / 3 |
Completeness | Clearly answers both 'what' (simplifies code for clarity without changing behavior) and 'when' with multiple explicit 'Use when...' clauses covering refactoring, readability issues, and accumulated complexity. | 3 / 3 |
Trigger Term Quality | Includes relevant terms like 'refactoring', 'clarity', 'maintain', 'extend', 'complexity', and 'code'. However, it misses common natural variations users might say such as 'clean up code', 'simplify', 'readable', 'messy code', 'spaghetti code', 'technical debt', or 'code smell'. | 2 / 3 |
Distinctiveness Conflict Risk | While it specifies a focus on simplification and clarity, it could overlap with general code review skills, refactoring skills, or code quality skills. The niche of 'simplifying code' is somewhat distinct but not sharply differentiated from broader code improvement skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
55%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is highly actionable with excellent workflow clarity, concrete code examples, and a thorough verification checklist. However, it is far too verbose for a skill file—much of the content (basic refactoring principles, common rationalizations, general software engineering wisdom) is knowledge Claude already possesses and wastes valuable context window tokens. The monolithic structure with no external file references compounds the verbosity problem.
Suggestions
Cut the content by 50-60%: remove 'Common Rationalizations' table, 'When to Use/When NOT to use' lists, principle explanations (1-4 especially), and 'Red Flags' section—Claude already knows these software engineering fundamentals.
Extract language-specific examples into separate files (e.g., typescript-patterns.md, python-patterns.md) and reference them from the main skill to reduce the monolithic structure.
Condense the Five Principles into a brief numbered list (1-2 lines each) rather than full sections with code blocks and explanations.
Move the pattern identification tables in Step 2 to a separate reference file, keeping only a brief summary of what to scan for in the main skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~300+ lines. It explains concepts Claude already knows well (what Chesterton's Fence is, why readable code matters, basic refactoring patterns like replacing loops with filter()). The 'Common Rationalizations' table, 'When to Use/When NOT to use' lists, and extensive principle explanations add significant token overhead without teaching Claude anything new. Much of this is general software engineering wisdom that Claude already possesses. | 1 / 3 |
Actionability | The skill provides fully executable, copy-paste ready code examples across TypeScript, Python, and React with clear before/after patterns. The simplification process has concrete steps, the pattern identification tables give specific signals and actions, and the verification checklist is directly actionable. | 3 / 3 |
Workflow Clarity | The four-step process (Understand → Identify → Apply Incrementally → Verify) is clearly sequenced with explicit validation checkpoints. Step 3 includes a feedback loop (run tests → if fail → revert and reconsider), and the final verification checklist ensures nothing is missed. The 'FOR EACH SIMPLIFICATION' loop is a well-defined feedback cycle. | 3 / 3 |
Progressive Disclosure | The entire skill is a monolithic wall of text with no references to external files and no content splitting. The language-specific guidance, pattern tables, common rationalizations, and red flags could all be separate reference files. For a skill this long, the lack of any progressive disclosure structure is a significant weakness. | 1 / 3 |
Total | 8 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- addyosmani/agent-skills
- Commit
f17c6e8
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.