CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

codebase-design

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

64

Quality

81%

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 codebase-design in mattpocock/skills

SKILL.md
Quality
Evals
Security

Quality

Content

71%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-written, token-efficient instruction skill with distinctive vocabulary and genuinely actionable design heuristics. Its main defect is structural: both "Going deeper" reference links point to files that do not exist in the bundle, leaving the progressive-disclosure path broken; its testability code examples also slightly over-explain concepts Claude already knows.

Suggestions

Add the referenced DEEPENING.md and DESIGN-IT-WICE/DESIGN-IT-TWICE.md files to the bundle (e.g. under references/) or remove the "Going deeper" links, so the skill's only two drill-down paths are not dangling.

Trim the "Designing for testability" TypeScript snippets to a one-line rule each (the dependency-injection and side-effects patterns are already known; only the vocabulary framing is new), saving tokens without losing guidance.

Add a short ordered procedure for applying the vocabulary to a concrete design task (e.g. identify modules -> apply the deletion test -> choose the seam -> count adapters), which would also lift workflow clarity to an explicit sequence.

DimensionReasoningScore

Conciseness

The body is lean and dense — nine terse glossary entries, compact principles, no padding — matching anchor 4 (efficient, minor instances that could be trimmed). It is not a 5 because the "Testable / Hard to test" TypeScript snippets re-teach dependency injection, a concept Claude already knows, though the surrounding framing in terms of the vocabulary keeps the over-explanation minor.

4 / 5

Actionability

Concrete, usable decision rules are given — "the deletion test", "One adapter means a hypothetical seam. Two adapters means a real one", the three-question interface checklist, and executable TypeScript examples — matching anchor 4 (mostly executable guidance with minor gaps). Not 5 because the guidance is judgment criteria for a vocabulary skill rather than copy-paste-ready instruction covering common cases end-to-end, and not 3 because nothing is pseudocode or vague.

4 / 5

Workflow Clarity

Organization is coherent and navigable (glossary, deep vs shallow, principles, testability application, relationships) with an explicit design checklist; there is no multi-step process to sequence and no destructive or batch operation that would require validation. Anchor 4 fits (clear structure, minor gaps); 5 is reserved for an explicit validated sequence, and the 115-line body with no step sequence for applying the vocabulary to a concrete design task falls short of that.

4 / 5

Progressive Disclosure

The "Going deeper" section signals one-level-deep references clearly and the main body is well organized, but both referenced files (DEEPENING.md and DESIGN-IT-TWICE.md) are absent from the bundle — neither references/ nor any other directory contains them — so both navigation paths are dangling. Anchor 3 (structure present but navigation does not actually work) fits better than anchor 4, where gaps would be minor; a fully broken two-link "Going deeper" section is more than a minor organization gap.

3 / 5

Total

15

/

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 answers both what (shared deep-module design vocabulary) and when, with multiple concrete, natural trigger phrases. Its only weaknesses are minor: a slightly abstract what-clause and a few missing synonyms that leave small overlap risk with general refactoring skills.

DimensionReasoningScore

Specificity

The when-clause lists several concrete actions — "design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable" — which sits at anchor 4 (several specific actions, minor gaps). It falls short of 5 because the what-clause ("Shared vocabulary for designing deep modules") is a single capability and no full inventory of actions is given, but exceeds 3 because more than 1-2 concrete actions are explicitly named.

4 / 5

Completeness

"Shared vocabulary for designing deep modules" explicitly states what the skill provides, and "Use when the user wants to... find deepening opportunities, decide where a seam goes... or when another skill needs the deep-module vocabulary" explicitly answers when with multiple concrete trigger phrases. This matches anchor 5 and is above anchor 4, where the when would be less explicit or specific.

5 / 5

Trigger Term Quality

Natural phrases a user would actually say are present ("improve a module's interface", "make code more testable", "design"), alongside distinctive terms like "deepening" and "seam". Coverage is good but misses common synonyms users might say instead ("refactor", "decouple", "architecture"), placing it at anchor 4 rather than 5, and clearly above 3 since multiple natural variations are covered.

4 / 5

Distinctiveness Conflict Risk

Niche terms ("deep module", "seam", "deepening opportunities") create a distinctive profile, but "design or improve a module's interface" overlaps with generic refactoring/architecture skills — anchor 4 (mostly distinct, minor overlap risk) rather than 5. It is well above anchor 3 because the deep-module vocabulary is not interchangeable with adjacent skills.

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: 2 missing

Warning

Total

15

/

16

Passed

Repository

withcoral/coral

Path

.agents/skills/codebase-design/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.