improve-codebase-architecture

Find deepening opportunities in a codebase. Use when the user asks to "improve architecture", "find refactoring opportunities", "consolidate modules", "make code more testable", or wants the codebase made more AI-navigable.

Quality

78%

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 ./skills/improve-codebase-architecture/SKILL.md

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 content is a well-organized, actionable instruction-only skill with a clear sequenced workflow and load-bearing vocabulary. Its main defect is progressive disclosure: the body repeatedly offloads detail to LANGUAGE.md and INTERFACE-DESIGN.md, neither of which exists in the bundle, leaving dead references.

Suggestions

Add the missing LANGUAGE.md and INTERFACE-DESIGN.md to the bundle (e.g., under references/), or inline the "full definitions" and "full principle list" the body promises, so the offloaded detail is actually reachable.

Add an explicit verification checkpoint before presenting candidates (e.g., confirm each candidate passes the deletion test and is checked against existing ADRs) to strengthen workflow clarity with a feedback loop.

Tighten the glossary entries and the deletion-test illustration to remove the remaining exposition and lift conciseness toward fully lean.

Dimension	Reasoning	Score
Conciseness	The body is efficient and assumes Claude's competence, and the glossary is load-bearing skill vocabulary rather than redundant concept explanation; a few glossary entries and illustrative explanations (e.g., the deletion-test paragraph) could still be trimmed, keeping it below the fully lean anchor 5.	4 / 5
Actionability	Guidance is concrete and actionable with specific tool calls (Agent tool, subagent_type=Explore), quoted prompts ("Which of these would you like to explore?"), and explicit decision triggers; step 3's grilling loop is intentionally open-ended, leaving minor gaps versus fully prescribed execution.	4 / 5
Workflow Clarity	A clearly sequenced three-step process (Explore, Present candidates, Grilling loop) includes the deletion-test filter and an explicit user-confirmation gate as checkpoints, but it lacks explicit validate-fix-retry feedback loops, leaving minor validation gaps.	4 / 5
Progressive Disclosure	The body is well-structured with clearly signaled one-level-deep references to LANGUAGE.md and INTERFACE-DESIGN.md, but those files are absent from the bundle, so the offloaded "full definitions" and "full principle list" are unreachable and navigation breaks at the first hop.	3 / 5
	Total	15 / 20 Passed

Description

86%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 excels at completeness and trigger-term coverage, pairing a clear purpose statement with multiple natural, explicit trigger phrases. Specificity is the main weakness since only one concrete action is named, and there is minor overlap risk with general refactoring skills.

Dimension	Reasoning	Score
Specificity	The phrase "Find deepening opportunities in a codebase" names the domain and one concrete action, but offers only that single action rather than the several specific actions of a 4 or the comprehensive coverage of a 5.	3 / 5
Completeness	It clearly states what the skill does ("Find deepening opportunities in a codebase") and explicitly when to use it ("Use when the user asks to ..." with concrete trigger phrases), matching the anchor that requires both an explicit what and when.	5 / 5
Trigger Term Quality	Five natural, quoted trigger phrases ("improve architecture", "find refactoring opportunities", "consolidate modules", "make code more testable", "made more AI-navigable") give comprehensive coverage of phrases a user would actually say, with multiple synonyms; the file-extension criterion is N/A for a non-file skill.	5 / 5
Distinctiveness Conflict Risk	It carves a clear architecture niche with distinct triggers, but phrasing like "refactoring opportunities" and "improve architecture" carries minor overlap risk with general code-improvement or review skills, keeping it just below the minimal-conflict anchor 5.	4 / 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: 4 missing, 2 suspicious	Warning

	Total	15 / 16 Passed

Repository: tslateman/duet
Path: skills/improve-codebase-architecture/SKILL.md
Commit: 5647baf

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.