improve-codebase-architecture

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

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

67%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 a well-structured, mostly lean workflow with concrete commands and an explicit user-interaction checkpoint. Its main weakness is actionability: the central HTML report artifact is delegated to an external scaffold file rather than shown or bundled, leaving the most important executable detail one step removed.

Suggestions

Inline a minimal HTML scaffold or ensure HTML-REPORT.md ships in the skill bundle (e.g. under references/) so the core deliverable is directly executable.

Add a quick validation/preview step for the generated HTML (e.g. confirm the file opened, verify diagrams rendered) to create a feedback loop.

Trim the rationale sentences (e.g. 'Deepening a module pays off...') to keep the body fully lean.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes competence (e.g. 'Apply the deletion test', 'Run the /grilling skill') without explaining basic concepts. Minor over-explanation like 'Deepening a module pays off by making future changes to it easier' could be trimmed, so it sits at 4 rather than 5.	4 / 5
Actionability	Concrete commands are present ('git log --oneline', '$TMPDIR' fallback, 'xdg-open'/'open'/'start', '<tmpdir>/architecture-review-<timestamp>.html'), but the core deliverable — the HTML report scaffold — is deferred to an external file ('.agents/skills/improve-codebase-architecture/HTML-REPORT.md') with no inline scaffold. Not a 4 because the main executable artifact is incomplete in the body itself.	3 / 5
Workflow Clarity	Clear three-step sequence (Explore → Present HTML report → Grilling loop) with an explicit interaction checkpoint ('Do NOT propose interfaces yet. After the file is written, ask the user: Which of these would you like to explore?'). Not a 5 because there is no explicit validation/recovery loop for the generated HTML report.	4 / 5
Progressive Disclosure	Well-organized into an overview plus a numbered Process with clearly signaled, one-level-deep references ('/codebase-design', 'CONTEXT.md', 'HTML-REPORT.md'). Not a 5 because the referenced HTML-REPORT.md scaffold is not present in the skill bundle, leaving a minor navigation gap.	4 / 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 actions and a clear 'what', but omits any 'Use when...' trigger guidance and leans on skill-specific jargon ('deepening opportunities', 'grill') that users are unlikely to voice naturally. Adding an explicit trigger clause and more common synonyms would lift completeness and trigger-term quality.

Suggestions

Append an explicit 'Use when...' clause, e.g. 'Use when reviewing codebase architecture, planning refactors, or looking for modules to deepen.'

Replace or supplement jargon ('deepening opportunities', 'grill through') with common user terms like 'refactoring opportunities', 'architecture review', 'walk through a decision'.

Add file-format or synonym triggers (e.g. 'architecture', 'module design', 'seams') to broaden natural keyword coverage.

Dimension	Reasoning	Score
Specificity	Quotes 'Scan a codebase for deepening opportunities', 'present them as a visual HTML report', 'grill through whichever one you pick' — three concrete, distinct actions. Not a 5 because 'deepening opportunities' and 'grill' are domain jargon rather than fully concrete capabilities, leaving minor coverage gaps.	4 / 5
Completeness	Has a clear 'what' (scan, present report, grill) but no 'Use when...' clause or equivalent explicit trigger guidance, so completeness is capped at 3 per the rubric guideline. It is not a 4 because 'when' is entirely absent rather than weakly implied.	3 / 5
Trigger Term Quality	'codebase' and 'visual HTML report' are natural user terms, but 'deepening opportunities' and 'grill through' are skill-internal jargon users would not naturally say. Missing common variations/synonyms like 'refactor', 'architecture review', 'code review'.	3 / 5
Distinctiveness Conflict Risk	The combination of architectural deepening review plus an HTML report plus a grilling loop is a fairly distinct niche. Not a 5 because it could overlap with general code-review or refactoring skills given the absence of explicit trigger phrases.	4 / 5
	Total	14 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: windmill-labs/windmill
Path: .agents/skills/improve-codebase-architecture/SKILL.md
Commit: 7915540

Reviewed: 3 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.