code-simplify
This skill should be used when the user asks to "simplify code", "clean up code", "refactor for clarity", "reduce complexity", "improve readability", "make this easier to maintain", or asks to simplify recently modified code.
52
57%
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-simplify/SKILL.mdQuality
Discovery
37%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description is essentially a list of trigger phrases with no explanation of what the skill actually does. While the trigger terms are excellent and natural, the complete absence of capability descriptions (the 'what') makes it impossible for Claude to understand the skill's actual functionality. It reads as a 'Use when...' clause without the preceding capability statement.
Suggestions
Add a capability statement before the trigger phrases, e.g., 'Refactors code by extracting functions, simplifying conditionals, reducing nesting depth, renaming for clarity, and removing dead code.'
Restructure to follow the pattern: '[What it does]. Use when [triggers].' to ensure both halves are covered.
Specify the types of simplification techniques or outputs (e.g., 'produces cleaner, more maintainable code with fewer lines and clearer naming') to distinguish from general code review skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description does not list any concrete actions or capabilities. It only lists trigger phrases but never explains what the skill actually does — no specific techniques like 'extract functions', 'rename variables', 'reduce nesting', etc. | 1 / 3 |
Completeness | The description answers 'when' very well but completely fails to answer 'what does this do'. There is no explanation of the skill's capabilities, techniques, or outputs. The 'what' is entirely missing, which is a critical gap. | 1 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger phrases users would actually say: 'simplify code', 'clean up code', 'refactor for clarity', 'reduce complexity', 'improve readability', 'make this easier to maintain'. These are highly natural and varied. | 3 / 3 |
Distinctiveness Conflict Risk | The trigger terms are fairly specific to code simplification/refactoring, but without describing concrete actions, it could overlap with general code review, linting, or refactoring skills. The lack of specificity about what it does makes it harder to distinguish from similar skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, well-crafted skill with excellent actionability and workflow clarity. The step-by-step process is clearly sequenced with validation checkpoints, stop conditions, and explicit safety constraints. The main weakness is moderate verbosity—some sections overlap or restate principles Claude already knows—and the monolithic structure could benefit from splitting detailed reference material into separate files.
Suggestions
Consolidate 'Operating Rules', 'Safety Constraints', 'Anti-Patterns', and 'Simplification Heuristics' into fewer sections to reduce overlap and improve conciseness.
Remove heuristics that restate general software engineering wisdom Claude already knows (e.g., 'Optimize for the next maintainer's comprehension time') and keep only project-specific or non-obvious guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is generally well-structured and avoids explaining basic concepts, but some sections are more verbose than necessary. The 'Operating Rules' section partially overlaps with 'Safety Constraints' and 'Anti-Patterns', and the 'Simplification Heuristics' section restates principles that Claude would already know (e.g., 'optimize for the next maintainer's comprehension time'). Could be tightened by ~20-30%. | 2 / 3 |
Actionability | The skill provides highly concrete, executable guidance throughout. Scope resolution includes specific git commands, the simplification passes are ordered and specific, verification steps name exact tool categories (formatter, lint, typecheck, tests), and the workflow is fully prescriptive with clear decision points. | 3 / 3 |
Workflow Clarity | The six-step workflow is clearly sequenced with explicit validation in step 5, feedback loops (run narrow checks first, then broader), clear skip conditions (--no-verify, --no-report), and well-defined stop conditions. The scope resolution is a detailed decision tree with fallback logic. Safety constraints serve as validation checkpoints throughout the editing process. | 3 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers and logical grouping, but it's a monolithic document with no references to external files. At ~120 lines, some sections (e.g., detailed simplification passes, anti-patterns, heuristics) could be split into separate reference files. However, since no bundle files exist, the inline approach is somewhat justified for a standalone skill. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- paulrberg/agent-skills
- Commit
11e1743
- 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.