CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

improve-architecture

Use when the codebase has architectural issues like high coupling, circular dependencies, or unclear boundaries - but a full migration is not needed.

Quality

67%

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 ./skills/improve-architecture/SKILL.md
SKILL.md
Quality
Evals
Security

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 content is a strongly actionable, well-gated workflow: measurable baselines, per-issue classification with targeted fixes, verify-and-revert loops, and before/after metrics. Its main weaknesses are redundancy across the Rules, Verification Protocol, and Output sections, plus an undefined $TARGET variable in the scan scripts.

Suggestions

Consolidate the redundant guidance: the Rules, Verification Protocol, Step 4, and final Output template repeat the same measure/verify/revert requirements — keep one authoritative statement of each.

Trim or remove the unsourced statistics in the Anti-Rationalization table ("70% IEEE study", "23% Gartner") or cite them properly, since dubious numbers cost tokens and credibility.

Fix the $TARGET/$ARGUMENTS inconsistency by defining $TARGET once (e.g., "TARGET=${ARGUMENTS:-.}") at the top of the scan commands so they are truly copy-paste ready.

DimensionReasoningScore

Conciseness

The body is dense and free of concept over-explanation, but has multiple sections that could be tightened: the Rules section restates workflow steps (measure first, one fix at a time, verify, revert), the final Output template duplicates the Step 5 Before/After table, and the Anti-Rationalization table carries questionable unsourced statistics ("Rewrites fail 70% of the time (IEEE study)", "~23% per year (Gartner)"). This is more than the 'minor instances' of anchor 4 but falls short of the pervasive padding of anchor 2.

3 / 5

Actionability

Concrete, executable guidance throughout: copy-paste bash scan commands, a classification table with fix strategies, and an explicit per-fix verification loop ("tsc --noEmit", "npm test", revert on failure). Minor gaps keep it from 5: the scan scripts use an undefined $TARGET variable while the skill defines the target as $ARGUMENTS, and verification assumes a TypeScript/npm project despite the scan covering .vue/.svelte files.

4 / 5

Workflow Clarity

The five-step workflow is clearly sequenced with explicit validation gates ("BLOCKED until scan produces metrics", "BLOCKED after each fix until compilation and tests pass"), a revert-and-re-evaluate feedback loop, dependency-ordered execution, and a 7-item verification checklist — a direct match to anchor 5's sequence, validation, feedback loops, and checklists.

5 / 5

Progressive Disclosure

With no bundle files provided, the single ~195-line SKILL.md is well-sectioned (When to Use, Workflow, Verification, Rules, Output) and easy to navigate. It scores below 5 because no content is offloaded (the long circular-dependency scan script and the Anti-Rationalization table could live in reference files), and above 3 because the structure is good and nothing is buried or clearly misplaced.

4 / 5

Total

16

/

20

Passed

Description

47%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 has strong trigger clarity — an explicit "Use when..." clause naming three concrete architectural conditions and an exclusion boundary for full migrations. However, it entirely omits the 'what': a reader cannot tell from the description alone whether the skill fixes, measures, documents, or reviews these issues.

Suggestions

Add a 'what' clause stating the core action, e.g., "Fixes architectural issues incrementally (circular dependencies, high coupling, unclear boundaries) with measured before/after metrics — Use when a full migration is not needed."

Add natural trigger synonyms users would say, such as "god files", "tangled codebase", or "module boundaries", to broaden keyword coverage.

State the key differentiator from plain refactoring (structural fixes only, no behavior changes) to reduce overlap with general refactoring skills.

DimensionReasoningScore

Specificity

The description names the domain with concrete issue types ("high coupling, circular dependencies, or unclear boundaries") but describes zero actions — it never says what the skill does (e.g., "fixes", "measures", "refactors"). It matches anchor 2 (domain named, actions minimal/generic) rather than 3, which requires 1-2 concrete actions; it is above 1 because the issue types are specific, not abstract.

2 / 5

Completeness

Only the 'when' is present ("Use when the codebase has architectural issues...") with no 'what' — the description never states what the skill actually does. This exactly matches anchor 2 ("only 'when' is present without 'what'"), and is not 3 because that anchor requires a clear 'what' with a weak 'when', which is the inverse of this description.

2 / 5

Trigger Term Quality

"high coupling", "circular dependencies", "unclear boundaries", and "architectural issues" are phrases users naturally say when they need this skill, giving good keyword coverage. It falls short of 5 because common variations are missing ("god files", "tangled codebase", "tech debt", "module boundaries"), and above 3 because the terms present are natural, not jargon-only or generic.

4 / 5

Distinctiveness Conflict Risk

The explicit boundary "but a full migration is not needed" carves out a niche from migration skills, and the named issue types are specific to architectural improvement. Minor overlap risk remains with closely related refactoring/code-review skills since the description does not exclude code-level refactoring, keeping it below 5 but above 3's broader overlap risk.

4 / 5

Total

12

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

fernandezbaptiste/specialist-agent

Path

skills/improve-architecture/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.