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

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

67%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 process content itself is strong: a well-sequenced, human-gated workflow with concrete paths, file conventions, and a tight glossary that justifies its length. The critical defect is that the skill as shipped is broken at its own architecture — every sidecar carrying the real depth (definitions, dependency classification, card contract, interface-design method) is referenced but absent from the bundle, so progressive disclosure fails and the deferred detail in actionability is unrecoverable.

Suggestions

Ship the referenced sidecars (LANGUAGE.md, DEEPENING.md, PRESENTING.md, INTERFACE-DESIGN.md) in the bundle, or inline their essentials and stop pointing at files the skill does not carry — 0 of 6 referenced files currently exist next to SKILL.md.

State invariant §10 once (e.g., in the intro blockquote) and refer back to it by id from 'What this skill does not do' and Hand off; do the same for the glossary-usage rules, which currently appear in three places.

Add an explicit self-check before ending phase 2 (e.g., verify each card uses only glossary terms and cites any conflicting record id), so validation does not rest solely on the human.

DimensionReasoningScore

Conciseness

The ~155-line body is dense and mostly earns its tokens — the glossary, deletion test, and scoping heuristics are kit-specific knowledge, not things Claude already knows — but there is repeated over-explanation: invariant §10 is stated three times (intro blockquote, "What this skill does not do", and Hand off), and glossary-usage rules appear in three places. That is a handful of trimmable spots rather than padding, fitting the 4 anchor ('efficient; minor instances of over-explanation') better than 3.

4 / 5

Actionability

Guidance is mostly executable: exact artifact paths to read first (docs/domain-glossary.md, docs/adr/, constitution/local-engineering.md), a concrete temp-file convention ("$TMPDIR falling back to /tmp… <tmpdir>/architecture-review-<timestamp>"), a fixed card schema with an enumerated recommendation scale, and the exact closing question ("Which of these would you like to explore?"). It stops short of 5 because the payload behind several steps — "Full definitions in LANGUAGE.md", "DEEPENING.md is how to classify the dependencies", PRESENTING.md's card contract — is deferred to files that are not in the bundle, leaving key details missing at execution time.

4 / 5

Workflow Clarity

A clearly sequenced four-phase process (scope→explore, present candidates, grilling loop, hand off) with most checkpoints present: read decision records before proposing, spawn exploration in fresh context, stop after writing the report and ask the human to pick, route style-level findings to /design-brief, mark record conflicts on the card. It is not 5 because validation is delegated to the human rather than explicit self-check steps, and the report-writing step has no verification of its own; the destructive/batch cap does not apply since exploration is read-only and the report lands outside the repo.

4 / 5

Progressive Disclosure

The body signals its references well and they are one level deep, but scored against the actual bundle structure every one is dangling: LANGUAGE.md, PRESENTING.md, DEEPENING.md, and INTERFACE-DESIGN.md are linked as ./-relative files and ../grill-with-docs/GLOSSARY-FORMAT.md and ADR-FORMAT.md as kit siblings, yet the bundle ships only SKILL.md — 0 of 6 referenced files exist. A dead link is worse than a buried one, so this lands below the 3 anchor ('references present but not clearly signaled'), matching the 2 anchor's structural failure.

2 / 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: third-person voice, a crisp capability statement, and an explicit multi-branch 'Use when' clause with genuinely natural trigger phrases. Its only weaknesses are reliance on kit-specific vocabulary (deepening, grilling) for the capability statement and a few missing common synonyms (refactor, restructure, technical debt) in the trigger list.

DimensionReasoningScore

Specificity

"Find deepening opportunities… 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" names several concrete actions (find/refactor candidates, ground them in glossary + decision records, grill the chosen one) with only minor gaps — the actions lean on kit jargon ("deepening", "grill") rather than plain capability terms, keeping it below the comprehensive 5 anchor.

4 / 5

Completeness

Both halves are explicit: the 'what' ("Find deepening opportunities… refactors that turn shallow modules into deep ones… then grill through whichever one the human picks") and a concrete 'when' clause ("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") — exactly the structure of the 5-anchor exemplar. Re-reading the 4 anchor ('when' could be more explicit) does not fit better; the trigger list is specific and multi-branch.

5 / 5

Trigger Term Quality

Natural phrases users would say are well covered — "improve architecture", "hard to change or hard to test", "consolidate tightly-coupled modules", "make a codebase more navigable" — but common synonyms like "refactor", "restructure", or "technical debt" are missing, matching the 'good coverage, a few natural terms missing' anchor rather than 5.

4 / 5

Distinctiveness Conflict Risk

The niche is distinct — architecture-level deepening reviews gated by domain glossary and binding decision records, explicitly design-only — with only minor overlap risk against generic refactoring or code-review skills triggered by "improve architecture"; it does not reach 5 because that trigger phrase is broad enough that a user wanting a routine refactor could land here.

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/ai-report-platform

Path

.agents/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.