improve-codebase-architecture

Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.

Quality

81%

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

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, actionable architecture-review process with a clear workflow and explicit user checkpoint. Its main weakness is progressive disclosure: the body points to several supporting files that are not present in the bundle.

Suggestions

Ship the referenced bundle files (LANGUAGE.md, INTERFACE-DESIGN.md, ATTRIBUTION.md) under references/ so the in-body links resolve, or inline the essential content and drop the dangling links.

Trim the inline glossary to the terms used in the body, relying on LANGUAGE.md for full definitions, to reduce redundancy with the referenced file.

Add an explicit validation/review checkpoint at the end of the grilling loop (e.g., re-confirm the deepened module's interface against the deletion test) to strengthen the workflow's feedback loop.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence, but the inline glossary repeats terms whose full definitions are already offloaded to LANGUAGE.md, a small amount of redundancy that could be trimmed.	4 / 5
Actionability	Gives concrete, executable guidance — 'use the Agent tool with subagent_type=Explore', specific friction prompts, the deletion test, and exact phrasings like 'Which of these would you like to explore?' — with only minor gaps typical of an instruction-only skill.	4 / 5
Workflow Clarity	A clear three-step sequence (Explore → Present candidates → Grilling loop) with an explicit user checkpoint ('Do NOT propose interfaces yet. Ask the user…') and inline side-effect rules; not a 5 because validation/feedback checkpoints are conversational rather than codified.	4 / 5
Progressive Disclosure	Structure and signaling are good (one-level-deep markdown links to LANGUAGE.md, INTERFACE-DESIGN.md, ATTRIBUTION.md), but none of the referenced files exist in the bundle, so the references are dangling rather than navigable.	3 / 5
	Total	15 / 20 Passed

Description

92%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 concretely states capabilities and provides an explicit, multi-trigger 'Use when' clause. Its only soft spot is the 'deepening opportunities' headline term being jargon rather than a natural user phrase.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable' — giving comprehensive coverage rather than vague abstraction.	5 / 5
Completeness	Explicitly answers both what ('Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/') and when ('Use when the user wants to improve architecture…') with concrete trigger phrases.	5 / 5
Trigger Term Quality	The 'Use when' clause surfaces natural phrases users would say ('improve architecture', 'refactoring opportunities', 'consolidate modules', 'testable'), though the headline term 'deepening opportunities' is skill-specific jargon a user would not naturally utter.	4 / 5
Distinctiveness Conflict Risk	The 'deepening opportunities' framing plus 'AI-navigable' and ADR/CONTEXT.md anchoring carve a clear niche distinct from generic refactoring skills, with minimal conflict risk.	5 / 5
	Total	19 / 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: 4 missing, 2 suspicious	Warning

	Total	15 / 16 Passed

Repository: belchman/claude-skills
Path: plugins/agentic-engineering/skills/improve-codebase-architecture/SKILL.md
Commit: 77a9e6b

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