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

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

78%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, opinionated instruction skill: the multi-step workflow is clearly sequenced with human-in-the-loop gates, guidance is concrete (paths, commands, artifact schemas), and detail is appropriately pushed to clearly annotated one-level-deep sidecars. The main trimmable costs are repeated restatements of the shared invariants and a lengthy provenance footer.

DimensionReasoningScore

Conciseness

The body is dense and assumes Claude's competence — no basic-concept explanations — but the shared-invariant §10 is stated three times (blockquote, "What this skill does not do", step 4) and the long provenance footer could be trimmed, matching "minor instances of over-explanation that could be trimmed".

4 / 5

Actionability

Concrete, executable guidance throughout: specific paths (docs/domain-glossary.md, docs/adr/, scripts/agents.config.sh), an exact temp-file naming pattern (<tmpdir>/architecture-review-<timestamp>), a defined card schema, and an exact closing question. Not a 5 because the exploration subagent and grilling loop lack example prompts, and no sample candidate card is shown.

4 / 5

Workflow Clarity

A clear four-step sequence (scope/explore → report → grilling → handoff) with genuine checkpoints: read decision records before proposing, apply the deletion test, human picks the candidate, session ends at an agreed design. It misses the 5 anchor because there are no explicit validate-fix-retry feedback loops, though the skill's only write is a temp report so the destructive/batch cap does not apply.

4 / 5

Progressive Disclosure

A clear overview with well-signaled one-level-deep references — LANGUAGE.md, DEEPENING.md, INTERFACE-DESIGN.md, and PRESENTING.md each introduced with a description of exactly what it carries (e.g., "[PRESENTING.md] carries that contract in full — the card layout, the visualisation patterns, the tone rules"). The glossary is split correctly: key terms inline, full definitions in the sidecar, matching the top anchor. No bundle files were shipped alongside SKILL.md, so this scores the reference structure as written.

5 / 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 that explicitly covers both what the skill does and when to use it, with mostly natural trigger phrases and a distinctive architectural-deepening niche. Its main gaps are the missing "refactor" keyword in the when-clause and slightly abstract phrasing of the actions.

DimensionReasoningScore

Specificity

Names several concrete actions — "find deepening opportunities", "refactors that turn shallow modules into deep ones", "grill through whichever one the human picks" — grounded in domain artifacts (domain language, binding decision records). It falls short of the 5 anchor because the actions are phrased somewhat abstractly and workflow stages like the report and ticket handoff are absent.

4 / 5

Completeness

Explicitly answers both what ("Find deepening opportunities... 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, matching the top anchor.

5 / 5

Trigger Term Quality

Natural user phrases are present — "hard to change", "hard to test", "improve architecture", "consolidate tightly-coupled modules", "more navigable" — but the most natural trigger word for this skill, "refactor", appears only in the what-clause and not in the when-clause, and common synonyms like "technical debt" or "clean up the code" are missing.

4 / 5

Distinctiveness Conflict Risk

The niche is distinct — architecture-level deepening reviews keyed to domain glossary and ADRs — but "improve architecture" and refactor-adjacent triggers carry minor overlap risk with general refactoring or code-quality skills. Clearer than the 3 anchor ("somewhat specific") but not a fully isolated niche.

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/tic-tac-toe-haskell

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.