CtrlK
BlogDocsLog inGet started
Tessl Logo

review-maintainability-and-code-quality

Review a change for whether the next person can understand it and change it safely. Use as one lens in a code review run.

55

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./code-review/skills/review-maintainability-and-code-quality/SKILL.md

The canonical home for this skill is tessl/code-review

SKILL.md
Quality
Evals
Security

Quality

Content

86%Scale 1-5

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

This is a high-quality, well-crafted skill that efficiently defines a maintainability review lens. It excels at conciseness and structure, with every section serving a clear purpose. The main area for improvement is adding a concrete example of a finding and its properly formatted report output, which would elevate actionability to the highest level.

Suggestions

Add one concrete example showing a code change with a maintainability issue and the expected report output, to make the Reporting section fully actionable.

DimensionReasoningScore

Conciseness

Every sentence carries weight. No explanations of concepts Claude already knows. The skill defines scope, method, threshold, and reporting format with zero padding. Each section is tightly scoped and avoids redundancy.

5 / 5

Actionability

The guidance is concrete and specific—it tells Claude exactly what to look for (loose types, misleading names, missing rationale) and how to report (name the question, cite precedent with file path, state structural fix). However, it lacks worked examples showing a sample finding or report output, which would make it fully executable.

4 / 5

Workflow Clarity

The Method section provides a clear sequence: read the standards chain, read names against behavior, read signatures as a consumer. The Threshold and Reporting sections act as decision checkpoints. However, the workflow is somewhat implicit rather than explicitly numbered/sequenced, and there's no explicit feedback loop. Since this is a non-destructive review lens (read-only analysis), the lack of validation loops is acceptable.

4 / 5

Progressive Disclosure

For a focused, single-purpose skill under 50 lines with no need for external references, the content is well-organized into clear sections (Scope, Method, Threshold, Reporting) that are easy to navigate. No content needs to be split out.

5 / 5

Total

18

/

20

Passed

Description

37%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 conveys a general sense of purpose — reviewing code changes for readability and maintainability — but lacks concrete actions, natural trigger terms, and explicit 'when to use' guidance. It reads more like an internal note about the skill's role in a workflow than a description optimized for skill selection among many options.

Suggestions

Add specific concrete actions the skill performs, e.g., 'Checks naming clarity, function complexity, comment quality, and whether abstractions are self-explanatory'.

Add explicit trigger guidance with natural terms: 'Use when the user asks for a code review, PR review, pull request feedback, or readability check on a diff or changeset'.

Clarify how this skill differs from other code review skills (e.g., security, performance, correctness) by naming the specific lens more precisely, such as 'readability and maintainability review'.

DimensionReasoningScore

Specificity

The description names the domain (code review) and one vague action ('review a change'), but doesn't describe concrete actions like checking naming conventions, evaluating test coverage, assessing documentation, or identifying complexity. The criteria 'whether the next person can understand it and change it safely' is somewhat specific but still abstract.

2 / 5

Completeness

The 'what' is present but vague (review a change for understandability and safety of future changes). The 'when' is weakly implied with 'Use as one lens in a code review run' — this tells Claude it's part of a larger workflow but doesn't provide explicit trigger phrases or conditions. The lack of a proper 'Use when...' clause with concrete triggers caps this at 3.

3 / 5

Trigger Term Quality

Contains 'code review' and 'change' as keywords, but misses many natural terms users would say like 'PR review', 'pull request', 'readability', 'maintainability', 'review my code', 'diff', or 'merge request'. The phrase 'next person can understand it' is not how users typically phrase requests.

2 / 5

Distinctiveness Conflict Risk

The focus on readability/maintainability as a specific 'lens' in code review provides some distinction, but 'review a change' is broad enough to overlap with other code review skills (e.g., security review, performance review). The phrase 'one lens in a code review run' suggests it's part of a multi-skill system, which helps somewhat but the boundaries aren't clearly drawn.

3 / 5

Total

10

/

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.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
tesslio/product-plugins
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.