CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

improve-codebase-architecture

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

56

Quality

71%

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

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/improve-codebase-architecture/SKILL.md

The canonical home for this skill is improve-codebase-architecture in mattpocock/skills

SKILL.md
Quality
Evals
Security

Quality

Content

71%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 well-structured, lean instruction skill with a clear three-phase workflow, concrete commands, and explicit user-interaction checkpoints. Its main defect is operational: the HTML-REPORT.md reference that carries the report scaffold is missing from the bundle, and the workflow depends on several sibling skills being available.

Suggestions

Add the missing HTML-REPORT.md (or inline a minimal scaffold) — the reference at line 53 points to a file that does not exist in the bundle.

Include a fallback if /codebase-design, /grilling, or /domain-modeling skills are unavailable, since the grilling loop currently has no inline path.

Add a lightweight validation checkpoint for the report step, e.g. verify the HTML file was written and the diagrams render before opening it for the user.

DimensionReasoningScore

Conciseness

The body is dense with directive guidance and explains nothing Claude already knows — no library tutorials, no concept primers. A few passages could be tightened (the Mermaid-vs-hand-built paragraph and the ADR-conflict paragraph carry extra words), which keeps it just below anchor 5's 'every token earns its place'.

4 / 5

Actionability

Concrete and executable in most places: exact temp-file pattern '<tmpdir>/architecture-review-<timestamp>.html', platform-specific open commands (xdg-open/open/start), an enumerated card schema with fixed badge values, and the exact question to ask the user. It falls short of anchor 5 because the actual HTML scaffold is delegated to HTML-REPORT.md, which does not exist in the bundle, and the process leans on external skills (/codebase-design, /grilling, /domain-modeling) without inline fallbacks.

4 / 5

Workflow Clarity

A clear three-step sequence (Explore → Present candidates → Grilling loop) with explicit checkpoints: 'Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"', plus inline side-effect rules for CONTEXT.md and ADRs. It is not anchor 5 because there is no validation step for the generated HTML report; it is above anchor 3 since checkpoints and the user-selection gate are explicit, and the writes are deliberately non-destructive (temp dir, outside the repo).

4 / 5

Progressive Disclosure

The body itself is well structured with clear sections and a single, clearly signaled one-level reference ('See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance') — but that file does not exist in the bundle (no references/ directory and no HTML-REPORT.md anywhere), so the promised scaffold is unreachable. This matches anchor 3 ('some structure... references present but' navigation is broken in practice) rather than anchor 4, which requires references to actually resolve.

3 / 5

Total

15

/

20

Passed

Description

58%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 states concrete, sequenced capabilities in third person, but it entirely omits when the skill should be used and leans on internal vocabulary ("deepening opportunities", "grill") that users would not naturally say. It is serviceable for a user-invoked command but weak as a triggerable skill description.

Suggestions

Add an explicit 'Use when...' clause naming natural trigger moments, e.g. 'Use when the user asks to improve codebase architecture, reduce coupling, or find refactoring opportunities.'

Include plain-language synonyms alongside the jargon so natural queries match: 'refactoring opportunities', 'shallow modules', 'architecture review' in addition to 'deepening opportunities'.

Clarify 'grill through' with plain wording such as 'then interrogate the chosen candidate's design' so the third action is understandable without the design vocabulary.

DimensionReasoningScore

Specificity

The description lists three concrete actions — "Scan a codebase for deepening opportunities", "present them as a visual HTML report", "then grill through whichever one you pick" — with only minor gaps. It falls short of anchor 5 because "deepening opportunities" and "grill through" are vocabulary-specific jargon rather than fully self-explanatory concrete actions, but it clearly exceeds anchor 3's '1-2 concrete actions' level.

4 / 5

Completeness

The 'what' is clear (scan, present an HTML report, grill through the picked candidate) but there is no 'when' clause at all — no 'Use when...' or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. This matches anchor 3 ('clear what but when is missing') and is not anchor 4, which requires both to be present.

3 / 5

Trigger Term Quality

Relevant keywords are present ("codebase", "visual HTML report") but natural phrases a user would actually say — "refactor", "architecture review", "improve the codebase", "technical debt" — are missing, and "deepening opportunities" is design jargon users rarely say. Anchor 4 requires 'good keyword coverage'; this has some but misses common variations, matching anchor 3.

3 / 5

Distinctiveness Conflict Risk

The deepening/HTML-report/grilling combination is a fairly distinct niche with minor overlap risk against general refactoring or code-review skills. It is not anchor 5 because the description lacks explicit distinguishing trigger phrases and 'codebase' scoping is broad enough to overlap with code-review and refactoring skills.

4 / 5

Total

14

/

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

coder/agent-tty

Path

.agents/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.