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.

Quality

61%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/code-simplification/SKILL.md

Quality

Content

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 well-structured with clear workflows, excellent code examples, and thorough verification steps, but it is far too verbose for its purpose. It extensively explains concepts Claude already understands (basic refactoring patterns, why readability matters, what Chesterton's Fence means) and includes large tables of rationalizations and red flags that add little actionable value. The monolithic structure with no progressive disclosure compounds the token waste.

Suggestions

Cut the content by 50-60%: remove the 'Common Rationalizations' table, the 'When to Use / When NOT to use' section, explanations of Chesterton's Fence, and trivially obvious code examples (filter, dict comprehension, redundant boolean return) that Claude already knows.

Extract language-specific examples into separate referenced files (e.g., examples/typescript.md, examples/python.md) to reduce the main skill's token footprint and improve progressive disclosure.

Remove or drastically condense the 'Red Flags' section — most items duplicate guidance already given in the principles and process steps.

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, common rationalizations table, basic refactoring patterns like filter/map, early returns, dict comprehensions). The 'Common Rationalizations' table and extensive 'When to Use / When NOT to use' sections add significant padding. Many code examples show trivially obvious simplifications that any competent coding agent already knows.	1 / 3
Actionability	The skill provides fully executable, copy-paste-ready code examples across TypeScript, Python, and React with clear before/after patterns. The step-by-step process includes concrete checklists, specific thresholds (50+ lines, 3+ nesting levels, 500-line rule), and explicit verification criteria.	3 / 3
Workflow Clarity	The four-step process (Understand → Identify → Apply Incrementally → Verify) is clearly sequenced with explicit validation checkpoints. The 'apply changes incrementally' step includes a feedback loop (make change → run tests → pass/fail → commit/revert), and the verification checklist at the end provides comprehensive validation gates.	3 / 3
Progressive Disclosure	The entire skill is a monolithic wall of text with no references to external files. Content that could be split out (language-specific examples, pattern tables, rationalizations table) is all inline, making the document very long. For a skill this size, splitting into referenced sub-files would significantly improve token efficiency.	1 / 3
	Total	8 / 12 Passed

Description

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 explicit 'Use when' clauses that clearly define trigger scenarios. However, it lacks specificity in the concrete actions it performs (only 'simplifies') 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 methods, reduces nesting, removes dead code, renames variables for clarity, simplifies conditionals'.

Include additional natural trigger terms users might 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, hard-to-read code, 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', 'readable', 'simplify', 'messy code', 'spaghetti code', 'technical debt', or 'code smell'.	2 / 3
Distinctiveness Conflict Risk	While it specifies simplification and clarity, it could overlap with general code review skills, refactoring skills, or code quality skills. The focus on 'simplifying' helps somewhat, but 'refactoring code' and 'reviewing code' are broad enough to conflict with other code-related skills.	2 / 3
	Total	9 / 12 Passed

Validation

100%

Warnings & errors only

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: 5e262b2

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

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.