CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

improve-codebase-architecture

Guided architecture review with an HTML report. Trigger: review/audit architecture, find refactoring candidates.

64

Quality

81%

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

77%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 tight, well-structured instruction body with an explicitly sequenced workflow, concrete commands and tool invocations, and clear user-interaction checkpoints. Its one material defect is a broken progressive-disclosure link: the referenced HTML-REPORT.md is absent from the bundle, leaving the report-generation step without its promised scaffold.

Suggestions

Ship the referenced HTML-REPORT.md alongside SKILL.md (or inline the essential scaffold and drop the link) so the 'full HTML scaffold, diagram patterns, and styling guidance' actually exists.

If keeping external references, place them under a references/ directory and list them in the body with explicit paths so the bundle structure is self-describing.

Trim rationale sentences (e.g. the YAGNI justification and the Mermaid editorial examples) to tighten conciseness without losing the directives.

DimensionReasoningScore

Conciseness

The body is dense and assumes competence — no space is spent explaining what architecture or git is, and nearly every line issues specific direction (e.g. 'walk back a good stretch of the commit history (git log --oneline)'). It sits at anchor 4 rather than 5 because a few passages carry rationale that could be trimmed, such as the YAGNI justification sentence and the extended Mermaid-vs-hand-built-visuals distinctions.

4 / 5

Actionability

Guidance is mostly executable: exact commands ('xdg-open <path>' on Linux, 'open <path>' on macOS), a concrete output path pattern ('<tmpdir>/architecture-review-<timestamp>.html'), named Skill-tool invocations ('codebase-design', 'grilling', 'domain-modeling'), and enumerated report-card fields with fixed badge values (Strong, Worth exploring, Speculative). It falls short of anchor 5 because the pointer to the full HTML scaffold — 'See [HTML-REPORT.md](HTML-REPORT.md)' — targets a file that does not exist in the bundle, leaving a gap in the most concrete deliverable guidance.

4 / 5

Workflow Clarity

The process is a clearly sequenced three-phase workflow (Explore → Present candidates as an HTML report → Grilling loop) with explicit checkpoints and feedback loops: 'Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"', branching rules for user-named directions, and ADR-conflict handling. This matches anchor 5's clear sequence with explicit checkpoints and error/edge-case recovery paths.

5 / 5

Progressive Disclosure

The main file is well-sectioned and the intent to split content is correct — the HTML scaffold is appropriately pushed out via 'See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance'. However, no bundle files exist (no references/, scripts/, or assets/) and the single referenced file is missing, so the one-level-deep reference is broken; per the guideline to score against the actual bundle structure, this lands at anchor 3 (structure present but undermined) rather than 4 (references mostly clear with only minor gaps).

3 / 5

Total

16

/

20

Passed

Description

78%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 concise, well-formed description that clearly states what the skill does and includes an explicit, labeled trigger clause with natural trigger phrases. Its main weakness is limited action coverage — the interactive exploration and domain-vocabulary integration work are not hinted at.

Suggestions

Add one more concrete capability to the description, e.g. '...then walk the chosen refactor through a constraints/decision loop', to lift specificity toward comprehensive action coverage.

Include a common synonym trigger such as 'improve code structure' or 'tech debt' to broaden natural-term coverage.

DimensionReasoningScore

Specificity

Names the domain ('Guided architecture review') plus roughly two concrete actions/deliverables ('with an HTML report', 'find refactoring candidates'), matching the anchor for naming a domain with 1-2 concrete actions but not comprehensive coverage. It falls short of anchor 4 because it omits the interactive candidate exploration, AGENTS.md/ADR integration, and deepening-refactor proposal work that the skill actually performs.

3 / 5

Completeness

It explicitly answers both questions: the 'what' ('Guided architecture review with an HTML report') and a labeled, concrete 'when' clause ('Trigger: review/audit architecture, find refactoring candidates'), matching anchor 5's requirement for both what AND when with concrete trigger phrases. It is not anchor 4 because the trigger guidance is already explicit and specific rather than merely present.

5 / 5

Trigger Term Quality

'Trigger: review/audit architecture, find refactoring candidates' supplies natural phrases a user would plausibly say, giving good keyword coverage — matching anchor 4 rather than 5 because common variations like 'improve code structure', 'design review', or 'tech debt' are absent, and it is clearly above anchor 3 since multiple relevant natural terms are present.

4 / 5

Distinctiveness Conflict Risk

'architecture review' and 'refactoring candidates' carve out a clear niche that is unlikely to fire for unrelated skills, though there is minor overlap risk with general code-review or refactoring skills — matching anchor 4 ('mostly distinct; minor overlap risk') and falling short of anchor 5's 'minimal conflict risk'.

4 / 5

Total

16

/

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

relative_links

Relative link issues: 1 missing

Warning

Total

15

/

16

Passed

Repository

YoizenSA/dev-ai-workflow

Path

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