CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

review-simplify

Review one code change, or one design (an OpenSpec change or an architecture doc), for needless complexity and rate it Low, Medium, or High. Looks for scope that could be narrower, edge cases that do not deserve machinery, state kept in several places, boundaries that only forward, and code or design parts whose reason to exist is gone. Use when asked to "simplify this diff", "is this overbuilt", "review this PR for simplicity", "review this spec or design for simplicity", or when a review loop runs the simplify lens. Read-only; it reports findings and does not fix them.

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

78%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.

A tightly written, highly actionable review procedure with an exact command set, rating rubric, and report template, weakened by one structural flaw: its central 'What to look for' section points to a `lens.md` that is absent from the bundle, leaving the code-target criteria unreachable. The skill is well-organized and concise, but the broken reference costs it both navigability and a fraction of its executability.

Suggestions

Ship `lens.md` with the skill (e.g., in `references/`) so the instruction "Read `lens.md` in this skill's directory and apply it" resolves — the current bundle contains only SKILL.md, making the core analysis criteria for code targets unreachable.

Inline a condensed version of the lens criteria for code targets, as the body already does for design targets under 'What to look for', so the skill remains operable even if the reference file is missing.

Add a verification checkpoint before writing the report, such as confirming each finding's `Where: <file>:<line>` location against the diff (or the spec file and heading for designs), to close the workflow's only validation gap.

DimensionReasoningScore

Conciseness

The body is lean and assumes Claude's competence throughout: it gives the exact command ("Read the change with `git -C <checkout> diff <base> <head>`. Add `-- <path>` to read one file.") with no git tutorial, defines the rating tiers in one tight paragraph, and never explains concepts Claude already knows. Every section instructs rather than describes; there is no padding to trim, which fits anchor 5 rather than anchor 4's "minor instances of over-explanation".

5 / 5

Actionability

Mostly executable guidance: exact diff command, explicit input contract with a recovery rule ("If the caller leaves one out, work it out and say what you used"), an inline list of design-target look-fors, and a copy-paste output template with field-by-field semantics. The gap is that the core analysis criteria for code targets are delegated to `lens.md` ("Read `lens.md` in this skill's directory and apply it"), and that file is not present in the bundle, so the single most load-bearing instruction cannot be executed from what ships here — slightly more than the "minor gaps" of anchor 5 but well above the pseudocode-level incompleteness of anchor 3.

4 / 5

Workflow Clarity

The sequence is clear and complete: identify target type, gather inputs, read the target via the given git command, apply the lens, assign a rating from defined thresholds, and emit the fixed report shape, with the output template acting as a checklist (including the explicit empty case "write 'No findings.'"). Being read-only, the destructive/batch validation cap does not apply. It falls short of anchor 5 only because there is no explicit checkpoint verifying findings before reporting (e.g., confirming each "Where: <file>:<line>" against the diff), leaving a minor validation gap at anchor 4.

4 / 5

Progressive Disclosure

The in-file structure is good — well-labeled sections (Targets, Inputs, Rules, Rating, Output format) and a single, clearly signaled reference ("Read `lens.md` in this skill's directory ... It explains how to judge scope, edge cases, coordination, and the shape of the code") that is one level deep. However, scored against the actual bundle structure, the referenced `lens.md` does not exist (no `lens.md`, no `references/` directory alongside SKILL.md), so navigation dead-ends at the skill's core judgment content; the body is also ~100 lines with the detailed criteria for code targets neither inlined nor resolvable, which is the "could be better organized" territory of anchor 3 rather than the clean split of anchor 4.

3 / 5

Total

16

/

20

Passed

Description

100%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.

An exemplary description: it states a precise, multi-part capability set, an explicit rating output, a read-only scope boundary, and a battery of natural trigger phrases covering code and design targets. Both the 'what' and 'when' questions are answered concretely with no padding or over-claims.

DimensionReasoningScore

Specificity

The description lists multiple concrete review actions — "scope that could be narrower", "edge cases that do not deserve machinery", "state kept in several places", "boundaries that only forward" — plus a concrete rating scheme ("rate it Low, Medium, or High") and an explicit mode ("Read-only; it reports findings and does not fix them"). Coverage of what the skill does is comprehensive with no vague filler, matching the anchor-5 example's level of concreteness rather than the minor-gaps level of anchor 4.

5 / 5

Completeness

Both halves are explicit: what ("Review one code change, or one design ... for needless complexity and rate it Low, Medium, or High", with the read-only scope stated) and when ("Use when asked to 'simplify this diff', 'is this overbuilt', 'review this PR for simplicity' ..."). This mirrors the anchor-5 example that clearly answers both what and when with concrete trigger phrases; anchor 4's "'when' could be more explicit" does not apply.

5 / 5

Trigger Term Quality

It quotes natural phrases a user would actually say — "simplify this diff", "is this overbuilt", "review this PR for simplicity", "review this spec or design for simplicity" — covering variations across diff, PR, spec, and design targets, plus the programmatic trigger "when a review loop runs the simplify lens". This is comprehensive natural-term coverage including synonyms, the anchor-5 standard; anchor 4 ("a few natural terms missing") would understate it.

5 / 5

Distinctiveness Conflict Risk

It carves a clear niche — a simplicity/needless-complexity lens that is read-only and reports findings — distinct from bug-focused code-review skills, and every trigger phrase carries a simplicity qualifier ("simplify", "overbuilt", "for simplicity") that disambiguates from a generic review request. Conflict risk is minimal, fitting anchor 5; the slight overlap with general PR-review skills is already resolved by those qualifiers, so anchor 4's "minor overlap risk" is a worse fit.

5 / 5

Total

20

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

Agenta-AI/agenta

Path

.agents/skills/review-simplify/SKILL.md

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.