improve-codebase-architecture

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

Quality

31%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

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

62%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a well-structured orchestration skill with a clear three-phase workflow and thoughtful decision points for side effects. Its main weaknesses are the missing referenced bundle file (HTML-REPORT.md) and the lack of executable code examples — the HTML report generation instructions are descriptive rather than showing concrete code snippets. The vocabulary enforcement and ADR-awareness add useful guardrails but also contribute to verbosity.

Suggestions

Provide the referenced HTML-REPORT.md bundle file, or inline a minimal executable HTML template showing the card structure, Tailwind/Mermaid CDN imports, and before/after diagram pattern.

Add a concrete code snippet for the temp file creation and OS-detection logic rather than just describing the path pattern and open commands.

Tighten the preamble — the design vocabulary cross-reference to /codebase-design could be a single sentence with a link rather than a bulleted list explaining each term.

Dimension	Reasoning	Score
Conciseness	The skill is reasonably efficient but includes some verbose phrasing and explanatory context that could be tightened. The preamble about design vocabulary and the repeated reminders about terminology usage add bulk, though most content is purposeful.	2 / 3
Actionability	The skill provides a clear process with specific steps and concrete details (temp dir paths, OS-specific open commands, HTML report structure with card fields), but lacks executable code examples. The HTML report section describes what to render but delegates to an HTML-REPORT.md scaffold that isn't provided. The exploration step is intentionally organic rather than prescriptive, which is appropriate but less actionable.	2 / 3
Workflow Clarity	The three-phase workflow (Explore → Present → Grilling loop) is clearly sequenced with explicit checkpoints: the user is asked to pick a candidate before proceeding, side effects are enumerated with clear triggers and actions, and there are decision points for ADRs and domain model updates. The feedback loop in step 3 is well-defined with conditional branching.	3 / 3
Progressive Disclosure	The skill references HTML-REPORT.md for detailed scaffold/styling guidance and delegates to other skills (/grilling, /codebase-design, /domain-modeling), which is good progressive disclosure structure. However, the bundle files note says no bundle files were provided, meaning HTML-REPORT.md is referenced but missing, which undermines the reference architecture. The inline content is also somewhat long for an overview.	2 / 3
	Total	9 / 12 Passed

Description

0%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description is vague, uses undefined jargon ('deepening opportunities', 'grill through'), lacks explicit trigger guidance, and provides no concrete actions that would help Claude distinguish this skill from other code analysis skills. The informal tone and absence of natural user-facing keywords make it very difficult for Claude to select this skill appropriately.

Suggestions

Define 'deepening opportunities' with concrete terms — e.g., 'Identifies refactoring candidates, reduces code complexity, and finds areas for improved abstraction' — so Claude and users understand what the skill actually does.

Add an explicit 'Use when...' clause with natural trigger terms like 'code review', 'refactor', 'tech debt', 'code quality', 'code analysis', or 'improvement suggestions'.

Replace informal language ('grill through whichever one you pick') with precise descriptions of the interactive workflow, e.g., 'Generates an interactive HTML report of findings and guides the user through detailed analysis of selected items.'

Dimension	Reasoning	Score
Specificity	The description uses vague, informal language like 'deepening opportunities' and 'grill through' without defining what these mean concretely. No specific actions (e.g., static analysis, refactoring suggestions, complexity metrics) are listed.	1 / 3
Completeness	While there is a rough 'what' (scan codebase, present report, explore an item), there is no 'Use when...' clause or explicit trigger guidance. The 'what' itself is too vague to be useful, and the 'when' is entirely missing.	1 / 3
Trigger Term Quality	'Deepening opportunities' is not a natural phrase users would say. Terms like 'codebase' and 'HTML report' are somewhat relevant but the core concept lacks recognizable trigger terms (e.g., 'code review', 'refactor', 'tech debt', 'code quality').	1 / 3
Distinctiveness Conflict Risk	'Scan a codebase' is extremely generic and could overlap with linting, security scanning, code review, refactoring, and many other code analysis skills. 'Deepening opportunities' is undefined jargon that doesn't carve out a clear niche.	1 / 3
	Total	4 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

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

Reviewed: 1 day 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.