improve-codebase-architecture

Scan a codebase for architectural deepening opportunities and present them in a visual HTML report. Use when the user asks for an architecture review or wants candidates to grill before choosing a refactor.

Quality

76%

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

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.

A well-organized, mostly executable instruction set with a clear multi-step workflow and good token efficiency. Its main weakness is progressive disclosure: the load-bearing HTML-REPORT.md reference points to a file that is missing, undermining both navigation and copy-paste actionability.

Suggestions

Add the missing HTML-REPORT.md bundle file (or inline the HTML scaffold into SKILL.md) so the load-bearing reference resolves and the report template is actually available.

Provide at least one minimal copy-paste-ready HTML skeleton inline in SKILL.md so the report step is executable even before the referenced file is opened.

Tighten the rationale sentences in the intro and Explore section (e.g. 'The aim is testability and AI-navigability' and 'Deepening a module pays off...') to lift conciseness toward the lean anchor.

Dimension	Reasoning	Score
Conciseness	The body is dense and directive, assuming Claude's competence and using domain vocabulary, with only a few rationale sentences ('The aim is testability and AI-navigability', 'Deepening a module pays off...') that could be trimmed to reach the lean 5 anchor.	4 / 5
Actionability	It gives concrete commands (git log --oneline, xdg-open, temp-dir resolution) and an explicit card schema with badge values, but the HTML scaffold is delegated to HTML-REPORT.md rather than provided inline, leaving a copy-paste gap short of fully executable.	4 / 5
Workflow Clarity	A clear three-step sequence (Explore, Present HTML report, Grilling loop) with explicit checkpoints (asking which candidate to explore; marking ADR conflicts) is present, though there is no explicit validate-fix-retry feedback loop.	4 / 5
Progressive Disclosure	The overview is well-structured with a clearly signaled one-level reference to HTML-REPORT.md, but that referenced file does not exist in the bundle, so navigation dead-ends and the separation it promises is not actually delivered.	3 / 5
	Total	15 / 20 Passed

Description

82%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 strong, third-person description that explicitly covers both capability and trigger conditions with concrete, natural language. It is comprehensive on completeness and distinctiveness, with only minor gaps in action enumeration and trigger synonyms.

Dimension	Reasoning	Score
Specificity	Names the domain ('architectural deepening opportunities') and two concrete actions ('Scan a codebase', 'present them in a visual HTML report'), matching the 1-2-actions anchor; it does not enumerate the several actions needed for the 4 anchor.	3 / 5
Completeness	It explicitly answers what ('Scan a codebase for architectural deepening opportunities and present them in a visual HTML report') and when ('Use when the user asks for an architecture review or wants candidates to grill before choosing a refactor') with concrete trigger phrases.	5 / 5
Trigger Term Quality	'architecture review', 'refactor', and 'candidates to grill' are natural phrases users would say, giving good coverage, but synonyms and extensions (e.g. 'design review', 'restructure') are absent so it stops short of comprehensive.	4 / 5
Distinctiveness Conflict Risk	The niche of architectural deepening surfaced as a visual HTML report with a grilling loop is clearly distinct from general code-review or refactor skills, with minimal conflict risk.	5 / 5
	Total	17 / 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: EpicenterHQ/epicenter
Path: .agents/skills/improve-codebase-architecture/SKILL.md
Commit: ecba024

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