CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

refactoring-analysis

Audit code quality and architectural health or plan refactoring using Fowler code smells and techniques; write prioritized findings to docs/_refacs/. Excludes formatting, performance, and security audits.

Quality

78%

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 ./.agents/skills/refactoring-analysis/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

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

An exemplarily lean, well-sequenced instruction skill that delegates detail to bundle files with condition-based pointers. Its main defects are a dangling reference to a nonexistent checklist file, an unreferenced script, and slightly abstract middle steps (ownership/coupling tracing) that keep actionability and workflow validation short of the top band.

Suggestions

Create the missing "checklists/analysis-checklist.md" referenced in step 5 (or point to an existing file), since the body's only validation checkpoint depends on it.

Add one short concrete example of a confirmed finding (smell name + evidence + improvement) inline to sharpen actionability for step 4's ranking step.

Either reference "scripts/validate-metadata.py" where relevant in the workflow or remove it from the bundle to keep the file structure intentional.

DimensionReasoningScore

Conciseness

The ~20-line body is lean and assumes competence: "Name the code smell, source evidence, and concrete improvement" states the quality bar without explaining what refactoring or code smells are. No padding or concept explanations anywhere; every token earns its place — matches anchor 5.

5 / 5

Actionability

Concrete guidance throughout: exact reference paths ("references/code-smells-catalog.md", "references/refactoring-techniques.md"), a concrete output convention ("docs/_refacs/<YYYYMMDD>-<slug>.md"), ranking criteria (impact, frequency, risk, effort), and conditional handling in step 6. Falls short of anchor 5 only because steps like "Trace ownership, coupling, call sites, and public boundaries" give direction without method specifics, and no example finding is shown inline.

4 / 5

Workflow Clarity

A clear six-step sequence with explicit branch handling ("If the user requested an audit only... If they already authorized refactoring") and a verification checkpoint ("Check material citations and reasoning with checklists/analysis-checklist.md"). Matches anchor 4 rather than 5 because the validation loop is thin — the checklist citation is the only explicit checkpoint, and the referenced checklist file does not exist in the bundle.

4 / 5

Progressive Disclosure

The body is an overview with well-signaled, one-level-deep references tied to conditions ("Consult references/solid-ddd-context.md only for a domain-model question"), and a template asset is correctly externalized. Scored against the actual bundle: all referenced files exist except "checklists/analysis-checklist.md", which is dangling, and "scripts/validate-metadata.py" is present but unreferenced — minor organization gaps that hold this at anchor 4 instead of 5.

4 / 5

Total

17

/

20

Passed

Description

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

A specific, well-fenced description that names concrete capabilities and a concrete output location, but it omits any "Use when..." trigger clause, which caps its completeness and weakens discoverability. Adding explicit trigger conditions and common synonyms (e.g., technical debt) would raise it to the top band.

Suggestions

Add an explicit trigger clause, e.g. "Use when the user asks to refactor code, audit code quality, or mentions code smells, technical debt, or Fowler refactoring techniques."

Include common user synonyms such as "technical debt" and "clean up code" alongside "code smells" and "refactoring" to broaden natural trigger coverage.

Consider naming the primary deliverable format (a dated markdown report) in the description so the "what" coverage is fully comprehensive.

DimensionReasoningScore

Specificity

Quotes: "Audit code quality and architectural health", "plan refactoring using Fowler code smells and techniques", "write prioritized findings to docs/_refacs/" — three concrete actions with a specific output location and method. Matches anchor 4 (several specific actions, minor gaps); not 5 because "architectural health" is generic and coverage of the workflow is not comprehensive, and not 3 because it lists more than 1-2 concrete actions.

4 / 5

Completeness

The "what" is clear (audit code quality, plan refactoring, write prioritized findings to docs/_refacs/), but there is no "Use when..." clause or equivalent explicit trigger guidance — per judging guidelines this caps completeness at 3. It is not 2 because the "what" is concrete and specific, not vague.

3 / 5

Trigger Term Quality

Natural terms present: "refactoring", "code smells", "code quality", "Fowler", "audit" — phrases users would plausibly say. Missing common variations like "technical debt", "clean up code", or "improve design", so it fits anchor 4 rather than 5, and clearly exceeds anchor 3's partial keyword coverage.

4 / 5

Distinctiveness Conflict Risk

The Fowler/code-smells framing carves a clear niche, and "Excludes formatting, performance, and security audits" explicitly fences off adjacent audit skills. Minor overlap risk remains with general code-review skills, matching anchor 4 rather than 5; it is well above anchor 3's "could still overlap with similar skills".

4 / 5

Total

15

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

Total

15

/

16

Passed

Repository

compozy/compozy

Path

.agents/skills/refactoring-analysis/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.