improve-codebase-architecture

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

Quality

65%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

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

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.

The body is well-structured, concise, and actionable with a clear gated workflow, but it leans on a referenced HTML-REPORT.md for the bulk of the technical HTML/diagram detail, and that file is missing from the bundle, breaking the progressive-disclosure path.

Suggestions

Ship the referenced HTML-REPORT.md (or inline its essential scaffold) so the deferred HTML/diagram guidance is actually reachable; a broken reference is the lowest-scoring dimension here.

Tighten the OS-specific open/temp-dir paragraph into a compact form (e.g. a short lookup) to move conciseness from 4 toward 5.

Add a light validation checkpoint for the generated HTML report (e.g. confirm the file wrote successfully before opening it) to strengthen workflow_clarity's feedback loop.

Dimension	Reasoning	Score
Conciseness	The body largely assumes Claude's competence and avoids explaining basics, but includes some trimmable detail such as enumerating every OS-specific open command and temp-dir fallback; matches the 'efficient with minor over-explanation' anchor rather than the fully lean 5.	4 / 5
Actionability	Gives concrete, executable guidance — Agent tool with subagent_type=Explore, explicit temp-dir path pattern, OS-specific open commands, a defined card schema and badge values — but defers the core HTML scaffold to HTML-REPORT.md, which is a minor gap given that file's absence.	4 / 5
Workflow Clarity	A clear three-step sequence (Explore → Present HTML report → Grilling loop) with an explicit gate ('Do NOT propose interfaces yet ... ask the user: Which of these would you like to explore?'); not a 5 because there are no explicit validate/fix/retry feedback loops for the report-generation step.	4 / 5
Progressive Disclosure	Sections are well-organized and the reference to HTML-REPORT.md is clearly signaled at one level deep, but that referenced file is not present in the bundle, so the deferred detail (HTML scaffold, diagram patterns, styling guidance) is unreachable — a real navigation gap.	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 is specific and action-oriented, clearly stating what the command does across three concrete steps, but it omits any explicit 'when to use' trigger guidance and relies on domain jargon ('deepening opportunities') rather than natural user phrases.

Suggestions

Add a 'Use when...' clause naming natural triggers, e.g. 'Use when the user wants to review or improve codebase architecture, find refactoring opportunities, or surface design friction.'

Soften or gloss the jargon term 'deepening opportunities' with a plain-language synonym so users who don't know the vocabulary still recognize the skill.

Include common synonyms/file cues (architecture, refactoring, shallow modules, design review) to broaden trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Lists three concrete actions — 'Scan a codebase for deepening opportunities', 'present them as a visual HTML report', 'then grill through whichever one you pick' — which matches the anchor for several specific actions with minor gaps; not a 5 because 'deepening opportunities' is domain jargon rather than fully unpacked capabilities.	4 / 5
Completeness	Has a clear 'what' (scan, present HTML report, grill) but no 'Use when...' clause or equivalent explicit trigger guidance, which per the guidelines caps completeness at 3.	3 / 5
Trigger Term Quality	Includes some relevant keywords ('codebase', 'visual HTML report') but leans on the jargon term 'deepening opportunities' rather than natural user phrases like 'review my architecture' or 'find refactoring opportunities', missing common synonyms and variations.	3 / 5
Distinctiveness Conflict Risk	The combo of a visual HTML architecture report plus an interactive grilling loop carves a fairly distinct niche with only minor overlap risk against the referenced /codebase-design skill.	4 / 5
	Total	14 / 20 Passed

Validation

93%

Warnings & errors only

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

Criteria	Description	Result
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: coder/agent-tty
Path: .agents/skills/improve-codebase-architecture/SKILL.md
Commit: ebff2c2

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.