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?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/code-simplification/SKILL.md

The canonical home for this skill is code-simplification in addyosmani/agent-skills

Quality

Content

55%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill is thorough and highly actionable with excellent workflow clarity and concrete executable examples. However, it is severely over-long for a skill file, explaining many concepts Claude already knows (basic refactoring patterns, what Chesterton's Fence means, why readable code matters) and inlining extensive reference material that should be split into separate files. The content would be significantly more effective at roughly one-third its current length.

Suggestions

Cut the content by 60-70%: remove explanations of concepts Claude already knows (Chesterton's Fence definition, why readability matters, basic refactoring patterns like filter vs for-loop, dict comprehensions). Keep only the process steps, the pattern identification tables, and the verification checklist.

Move language-specific examples and the Common Rationalizations table into separate referenced files (e.g., EXAMPLES.md, PATTERNS.md) to improve progressive disclosure and reduce the main file to an actionable overview.

Remove the 'When to Use' / 'When NOT to use' section or reduce it to 2-3 bullet points — the YAML frontmatter description already covers this, and Claude can infer appropriate usage contexts.

Consolidate the 'Red Flags' and 'Verification' sections into a single compact checklist since they overlap significantly (e.g., both mention not modifying tests, staying in scope, following conventions).

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, what guard clauses are, basic refactoring patterns like filter vs for-loop). The 'Common Rationalizations' table, 'Red Flags' list, and extensive language-specific examples all cover ground that any competent coding agent already understands. Much of this could be cut to under 100 lines without losing actionable value.	1 / 3
Actionability	The skill provides fully executable, concrete code examples across TypeScript, Python, and React with clear before/after patterns. The simplification process has specific, actionable steps with concrete checklists and the pattern identification tables give precise signals and responses.	3 / 3
Workflow Clarity	The four-step simplification process is clearly sequenced with explicit validation checkpoints (run tests after each change, revert if tests fail, compare before/after). The feedback loop of make change → test → commit or revert is well-defined, and the verification checklist at the end provides a comprehensive final validation gate.	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, common rationalizations) is all inline, making the file unnecessarily long. For a skill this size, there should be clear separation into overview + referenced detail files.	1 / 3
	Total	8 / 12 Passed

Description

67%Scale 1-3

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, which is its greatest strength. However, it lacks specificity in the concrete actions it performs (only 'simplifies') and could be more distinctive by listing specific simplification techniques. The trigger terms are adequate but could benefit from broader coverage of natural user language.

Suggestions

Add specific concrete actions like 'extracts methods, reduces nesting, removes dead code, renames for clarity, simplifies conditionals' to improve specificity.

Include additional natural trigger terms users might say, such as 'clean up code', 'code smell', 'too complex', 'hard to understand', or 'messy code'.

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 abstract.	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', 'read', 'maintain', 'extend', and 'complexity', which users might naturally say. However, it misses common variations like 'clean up code', 'simplify', 'reduce complexity', 'code smell', 'readable', or specific language references.	2 / 3
Distinctiveness Conflict Risk	While it specifies 'simplifying for clarity' and 'without changing behavior', it could overlap with general code review skills, refactoring skills, or code quality skills. The niche is somewhat defined but not sharply distinct from related coding 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: finlay611/agent-skills
Path: skills/code-simplification/SKILL.md
Commit: fea75b1

Reviewed: 4 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.