CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

improve-codebase-architecture

Find deepening opportunities in a codebase — refactors that turn shallow modules into deep ones — informed by the project's domain language and its binding decision records, then grill through whichever one the human picks. Use when an area has become hard to change or hard to test, or when the user asks to improve architecture, consolidate tightly-coupled modules, or make a codebase more navigable.

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/improve-codebase-architecture/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

63%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-sequenced, opinionated process skill with genuinely actionable guidance (explicit gates, temp-file contract, defined vocabulary) and good structural instincts. Its two real weaknesses are the triple repetition of the §10 invariant plus rhetorical padding, and a progressive-disclosure design whose five referenced sidecars are entirely absent from the bundle, leaving the report format, dependency classification, and interface-design method unspecified in practice.

Suggestions

Ship the referenced sidecars (LANGUAGE.md, PRESENTING.md, DEEPENING.md, INTERFACE-DESIGN.md) in the bundle, or inline their essential content — as delivered, every load-bearing reference in the body points at a file that does not exist.

State shared invariant §10 once (e.g., in the opening context block) and merely cite it elsewhere; it is currently fully re-explained in three places.

Trim rhetorical asides ('a second, staler glossary', 'a review that argues with the archive gets ignored') and add a fallback for the grilling step when the human rejects all candidates without a load-bearing reason.

DimensionReasoningScore

Conciseness

The body assumes Claude's competence and avoids basic-concept padding, but shared invariant §10 is explained in three separate places (the context blockquote, 'What this skill does not do', and 'Hand off') and rhetorical asides like 'a repo that accumulates dated architecture reports has acquired a second, staler glossary' could be trimmed. Mostly efficient, but noticeably tightenable.

3 / 5

Actionability

Concrete, executable guidance throughout for an instruction-only skill: temp-dir resolution via '$TMPDIR' with a '/tmp' fallback and a '<tmpdir>/architecture-review-<timestamp>' filename pattern, an enumerated card structure, an explicit recommendation-strength enum (Strong / Worth exploring / Speculative), and the exact closing question to ask. Minor gaps: the grilling substance and card layout are delegated to sidecars, and there is no guidance for the case where no candidates are found.

4 / 5

Workflow Clarity

A clear four-step sequence (scope → explore → report → grilling → handoff) with explicit checkpoints: read the glossary and binding decision records before proposing, and 'After the file is written, ask: Which of these would you like to explore?' as a hard human gate. The non-rigid exploration is explicitly justified. Minor gaps: no handling for the human rejecting every candidate without a load-bearing reason.

4 / 5

Progressive Disclosure

The reference scheme is well-designed on paper — one level deep, each sidecar (LANGUAGE.md, PRESENTING.md, DEEPENING.md, INTERFACE-DESIGN.md) clearly signaled with what it contains — but scored against the actual bundle structure, none of these files exist and no references/, scripts/, or assets/ directories are present. Every load-bearing reference is dangling, so the disclosure structure cannot actually be navigated.

3 / 5

Total

14

/

20

Passed

Description

83%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 description: it explicitly states what the skill does and when to use it, in third-person imperative voice, with concrete and mostly natural trigger phrases covering testability, changeability, consolidation, and navigability. Its only weaknesses are jargon-tinged action naming ('deepening', 'grill through') and a residual overlap risk with generic refactoring skills.

DimensionReasoningScore

Specificity

Lists several specific actions — 'Find deepening opportunities', 'refactors that turn shallow modules into deep ones', 'consolidate tightly-coupled modules', 'grill through whichever one the human picks' — with only minor coverage gaps. Not a 5 because key actions are phrased in the skill's internal jargon ('deepening', 'grill') rather than plain concrete terms.

4 / 5

Completeness

Clearly and explicitly answers both: what ('Find deepening opportunities in a codebase — refactors that turn shallow modules into deep ones — … then grill through whichever one the human picks') and when ('Use when an area has become hard to change or hard to test, or when the user asks to improve architecture, consolidate tightly-coupled modules, or make a codebase more navigable') with concrete trigger phrases. The 'when' clause is explicit and multi-triggered, fitting the 5 anchor rather than the 4 anchor's 'could be more explicit'.

5 / 5

Trigger Term Quality

Good natural coverage: 'hard to change', 'hard to test', 'improve architecture', 'consolidate tightly-coupled modules', 'make a codebase more navigable' are phrases users would actually say. A few natural terms are missing — 'refactor' as a user ask, 'tech debt', 'cleanup', 'module boundaries'.

4 / 5

Distinctiveness Conflict Risk

A clear niche (architecture-deepening review driven by domain language and decision records) with distinct triggers. Minor overlap risk remains with a generic refactoring or code-review skill, since 'improve architecture' is a broad ask a user might direct at either.

4 / 5

Total

17

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 4 possibly missing (./DEEPENING.md, ./INTERFACE-DESIGN.md, ./LANGUAGE.md, ./PRESENTING.md), 2 suspicious

Warning

referenced_paths_exist

Referenced path issues: 2 possibly missing (scripts/agents.config.sh, scripts/agents.lib.sh)

Warning

Total

14

/

16

Passed

Repository

agranado2k/google-books-clojure

Path

.claude/skills/improve-codebase-architecture/SKILL.md

Reviewed

Table of Contents

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.