CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

improve-codebase-architecture

Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.

72

Quality

90%

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

The canonical home for this skill is improve-codebase-architecture in mattpocock/skills

SKILL.md
Quality
Evals
Security

Quality

Content

93%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.

An exceptionally well-crafted instruction skill: it teaches a precise, self-contained vocabulary, gives concrete and copy-paste-ready direction at every stage, and cleanly defers deep material to one-level-deep references. The only notable gap is in the Explore stage, which lacks stopping criteria for how much exploration is enough and how many candidates to present, leaving a minor validation gap in an otherwise explicit workflow.

DimensionReasoningScore

Conciseness

Every section carries non-obvious, skill-specific content: the glossary redefines familiar words with precise project meanings ("Interface — everything a caller must know... Not just the type signature"; "Seam — ... Use this, not 'boundary'"), and full definitions are deferred to LANGUAGE.md rather than inlined. There is no filler explaining concepts Claude already knows, so it sits at the lean/efficient anchor rather than the minor-trim anchor of 4.

5 / 5

Actionability

For an instruction-only skill the guidance is fully executable: a concrete tool invocation ("use the Agent tool with `subagent_type=Explore`"), five specific friction questions, the deletion-test procedure, a fixed candidate format (Files/Problem/Solution/Benefits), a literal question to ask the user, and copy-paste-ready framing text for the ADR offer. It matches the anchor for specific, ready-to-use guidance covering the common cases.

5 / 5

Workflow Clarity

The three-stage sequence is clearly ordered with an explicit user gate ("Do NOT propose interfaces yet. Ask the user: 'Which of these would you like to explore?'") and a decision rule for ADR conflicts. It falls short of 5 because the Explore stage has no stopping or convergence criteria (when to stop exploring, how many candidates to surface) and there is no loop-back path when the user rejects every candidate rather than one — minor validation gaps consistent with anchor 4, but well above the missing-checkpoint level of 3.

4 / 5

Progressive Disclosure

The body is a clear overview with well-signaled, one-level-deep references: the working glossary is inlined while "Full definitions in [LANGUAGE.md]" and the full principles list are deferred, and [INTERFACE-DESIGN.md] is signaled exactly at the point of need. No reference nesting exists and the content split (summary inline, detail external) matches the top anchor; the cross-skill ../grill-with-docs/ links are a portability fragility but remain single-level and clearly signaled.

5 / 5

Total

19

/

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 with an explicit and well-phrased "Use when" trigger clause and multiple concrete capability terms. Its main weakness is leading with the undefined jargon phrase "deepening opportunities," which forces the reader into the body to understand the skill's core value. Trigger coverage is good but misses a few common synonyms users say when asking for architectural cleanup.

Suggestions

Decode the jargon in the headline action, e.g. "Find deepening opportunities — refactors that hide complexity behind small interfaces — in a codebase..." so the core value is understandable without opening the skill body.

Add one or two natural synonyms to the trigger clause (e.g. "restructure the codebase" or "reduce coupling between modules") that users commonly say when asking for architectural work.

Sharpen distinctiveness by naming the inputs that make this skill different (e.g. "informed by the domain language in CONTEXT.md") earlier or by scoping the when-clause to architectural/design-level refactors rather than any refactoring.

DimensionReasoningScore

Specificity

The description lists several concrete actions ("find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable") with only minor coverage gaps. It falls short of a 5 because the headline capability "Find deepening opportunities" is skill-internal jargon that a user browsing skills cannot decode without opening the body, and well above a 3 because action coverage goes beyond 1-2 generic actions.

4 / 5

Completeness

It explicitly answers both what ("Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/") and when ("Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable") with concrete trigger phrases, matching the anchor-5 exemplar structure exactly. The when-clause could not reasonably be more explicit.

5 / 5

Trigger Term Quality

Good natural keyword coverage: "improve architecture," "refactoring opportunities," "tightly-coupled modules," "testable" are phrases users would actually say. Not a 5 because common synonyms like "restructure," "clean up the codebase," or "reduce coupling" are missing; not a 3 because the present terms are well chosen rather than partial or generic.

4 / 5

Distinctiveness Conflict Risk

The skill occupies a clear niche (architecture deepening informed by CONTEXT.md domain language and ADRs), but the triggers "improve architecture" and "refactoring opportunities" have minor overlap risk with generic refactoring or code-cleanup skills. Not a 5 because those shared triggers could route a plain "help me refactor" request to the wrong skill; well above a 3 because the CONTEXT.md/ADR framing is distinctly its own.

4 / 5

Total

17

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

relative_links

Relative link issues: 4 missing, 2 suspicious

Warning

Total

15

/

16

Passed

Repository

SnowingFox/ai-skills

Path

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