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

76%

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

Quality

Content

73%Weight 40%Scale 1-5

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

The body is a well-structured, actionable process skill with a clear validated workflow and concrete examples. Its weakest dimension is conciseness: it spends significant tokens re-teaching basic refactoring patterns and concepts Claude already knows.

Suggestions

Trim the Language-Specific Guidance before/after examples to non-obvious cases only — async-wrapper removal, filter-vs-for-loop, dict comprehensions, and guard-clause early returns are patterns Claude already applies; keep only genuinely surprising or project-specific transformations.

Compress the Chesterton's Fence explanation in Step 1 to a one-line pointer ('understand why code exists before removing it — Chesterton's Fence') plus the checklist, rather than narrating the fence metaphor.

Consider moving the pattern/signal/simplification tables and Common Rationalizations table into a references/ file so SKILL.md stays a lean overview, improving both conciseness and progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is well-organized but lengthy and re-explains concepts Claude already knows (Chesterton's Fence spelled out, basic before/after patterns like async-wrapper removal, filter-vs-for-loop, dict comprehensions, guard-clause early returns), fitting 'mostly efficient but includes some unnecessary explanation or could be tightened'.	3 / 5
Actionability	Concrete pattern→signal→simplification tables, a specific threshold (Rule of 500), and copy-ready before/after code across TS/Python/React give mostly executable guidance, with minor gaps where direction is a judgment call (e.g. prop-drilling 'flag it, don't auto-refactor').	4 / 5
Workflow Clarity	A clear four-step process (Understand → Identify → Apply incrementally → Verify) with explicit validation (run tests after each change), a revert-and-reconsider feedback loop, and a verification checklist matches the top anchor; the destructive/batch cap does not apply because validation is present.	5 / 5
Progressive Disclosure	No bundle files exist, but the single self-contained file has clear section headers and easy navigation; over 50 lines so the simple-skill exception does not apply, and some reference-like material (language-specific guidance, pattern tables) could be split out, fitting 'good structure; minor organization gaps'.	4 / 5
	Total	16 / 20 Passed

Description

78%Weight 40%Scale 1-5

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 clearly and explicitly states what the skill does and when to use it, with strong natural trigger phrasing in third person. Its main limitation is specificity: it names a single core action rather than enumerating several distinct capabilities.

Dimension	Reasoning	Score
Specificity	Names the domain (code) and one concrete action ('Simplifies code for clarity') but does not enumerate multiple distinct capabilities, matching the 'names domain and 1-2 concrete actions, but not comprehensive' anchor.	3 / 5
Completeness	Explicitly answers 'what' ('Simplifies code for clarity') and 'when' with three concrete 'Use when...' trigger clauses, matching the top anchor for both what and when.	5 / 5
Trigger Term Quality	Includes natural phrases users would say ('refactoring code for clarity', 'harder to read, maintain, or extend', 'reviewing code that has accumulated unnecessary complexity') with good coverage, though a few synonyms (e.g. 'cleanup', 'tidy') are missing.	4 / 5
Distinctiveness Conflict Risk	The code-simplification-for-clarity niche is mostly distinct, with only minor overlap risk against general refactoring or code-review skills, fitting 'mostly distinct; minor overlap risk with closely related skills'.	4 / 5
	Total	16 / 20 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: addyosmani/agent-skills
Path: skills/code-simplification/SKILL.md
Commit: df1edb2

Reviewed: about 18 hours 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.