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

83%

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

SKILL.md
Quality
Evals
Security

Quality

Content

81%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 orchestration skill with an explicitly gated four-phase workflow and unusually concrete guidance (named paths, verbatim prompts, explicit output schemas). The main costs are redundancy — the behaviour-preserving §10 invariant and the finds-designs-doesn't-implement boundary are each stated multiple times — and references to sidecar files that are not shipped alongside the SKILL.md under review.

Suggestions

State shared invariant §10 once (e.g., in the opening blockquote) and reference it by number elsewhere; the same applies to the 'proposes and designs, does not implement' boundary, which is currently given in both the blockquote and the 'What this skill does not do' section.

Trim the inline glossary to the terms the body actually uses that are non-obvious (Depth, Seam, Locality, deletion test) and defer full definitions to LANGUAGE.md, which is already linked as the source.

Ensure the referenced sidecar files (LANGUAGE.md, PRESENTING.md, DEEPENING.md, INTERFACE-DESIGN.md and the ../grill-with-docs/ format files) ship with the skill bundle so the one-level-deep reference structure is navigable as written.

DimensionReasoningScore

Conciseness

Mostly dense and project-specific, but the same invariants are restated: shared invariant §10 appears three times (the opening blockquote, "What this skill does not do", and "Hand off"), and "finds and designs; it does not implement" appears twice (blockquote §7 and the not-do section). The inline glossary definitions of "Module", "Interface", and "Implementation" also overlap with what LANGUAGE.md already carries, so the body could be tightened without losing information.

3 / 5

Actionability

For an instruction-only skill the guidance is fully actionable: exact file paths to read first (docs/domain-glossary.md, docs/adr/, constitution/local-engineering.md, scripts/agents.config.sh), a named spawn prompt (.agents/prompts/cheap-reads.md), a concrete output convention (`<tmpdir>/architecture-review-<timestamp>`), an explicit card schema with enumerated fields and recommendation-strength labels, verbatim questions to ask ("Which of these would you like to explore?"), and precise rules for when to offer an ADR or update the glossary.

5 / 5

Workflow Clarity

The four phases (scope/explore, present candidates, grilling loop, hand off) are clearly sequenced with explicit checkpoints and gates: read glossary and decision records before proposing, "Do NOT propose interfaces yet", stop and ask which candidate to explore after writing the report, and "The session ends at an agreed design, not at a diff". The grilling loop with inline side-effect rules provides the feedback structure, and no destructive or batch operations apply.

5 / 5

Progressive Disclosure

The body is a genuine overview that pushes detail to well-signaled, one-level-deep references — "Full definitions in [LANGUAGE.md]", "[PRESENTING.md] carries that contract in full — the card layout, the visualisation patterns", "[DEEPENING.md] is how to classify the dependencies" — each stating what the file covers. However, none of the referenced files (LANGUAGE.md, PRESENTING.md, DEEPENING.md, INTERFACE-DESIGN.md, ../grill-with-docs/GLOSSARY-FORMAT.md, ../grill-with-docs/ADR-FORMAT.md) are present in the bundle being evaluated, so the split and navigation cannot be verified against actual files.

4 / 5

Total

17

/

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: concrete third-person statement of what the skill does, plus an explicit 'Use when' clause with multiple natural trigger phrases. Its only weaknesses are slightly broad architecture-improvement triggers with some overlap risk against general refactoring/review skills, and a few missing common synonyms (e.g., "reduce coupling", "technical debt").

DimensionReasoningScore

Specificity

The description lists several concrete actions — "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" — in third person. It sits at 4 rather than 5 because the middle clauses are modifiers on the same find-and-grill arc rather than additional distinct capabilities.

4 / 5

Completeness

It explicitly answers both questions: the what ("Find deepening opportunities... refactors that turn shallow modules into deep ones... then grill through whichever one the human picks") and an explicit when with concrete triggers ("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"). This matches the anchor-5 pattern of a clear what plus an explicit 'Use when' with multiple concrete trigger phrases.

5 / 5

Trigger Term Quality

The when-clause carries several natural phrases users would actually say: "hard to change or hard to test", "improve architecture", "consolidate tightly-coupled modules", "make a codebase more navigable". Common synonyms like "refactor the architecture", "reduce coupling", or "pay down technical debt" are absent, keeping it below the comprehensive anchor 5.

4 / 5

Distinctiveness Conflict Risk

The niche — architecture deepening review grounded in domain glossary and decision records — is clearly distinguishable, and triggers like "consolidate tightly-coupled modules" are distinctive. Broad triggers such as "improve architecture" and "make a codebase more navigable" could also plausibly fire for general refactoring or code-review skills, giving minor overlap risk characteristic of anchor 4 rather than the minimal-conflict anchor 5.

4 / 5

Total

17

/

20

Passed

Validation

75%

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

Validation — 12 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

metadata_version

'metadata.version' is missing

Warning

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

12

/

16

Passed

Repository

agranado2k/agentic-sdlc

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.