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.

Quality

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/codebase-design/SKILL.md

Quality

Content

57%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-organized conceptual reference with a strong glossary and useful testability examples, but it reads more as a vocabulary/principles document than an actionable design workflow. Workflow sequencing and clearly-signaled, verifiable progressive-disclosure references are the main gaps.

Suggestions

Add a concrete sequenced workflow for the core task (e.g., 'identify a shallow module → list its interface facts → sketch a smaller interface → move complexity behind it → verify via the deletion test') with explicit validation checkpoints.

Make the 'Going deeper' references clearly one-level-deep and resolvable (link the actual bundled DEEPENING.md / DESIGN-IT-WICE.md files from the skill bundle rather than repo-root paths), or inline a short summary of each so navigation is unambiguous.

Tighten the glossary by collapsing the adapter-vs-implementation distinction and rejected-framings entries to the essentials, reducing explanatory padding.

Dimension	Reasoning	Score
Conciseness	Mostly lean and assumes competence, but the glossary and rejected-framings sections include some explanatory padding (e.g., contrasting 'adapter' vs 'implementation' at length) that could be trimmed.	4 / 5
Actionability	Provides concrete testability code snippets and design heuristics ('deletion test,' 'one adapter means a hypothetical seam'), but the core design guidance is conceptual rather than executable — no runnable workflow for actually deepening a module in this file.	3 / 5
Workflow Clarity	Principles and design questions are listed but there is no sequenced multi-step process with validation checkpoints for the core task (deepening/redesigning a module); the 'Going deeper' pointers defer workflow to external files.	3 / 5
Progressive Disclosure	Structure is reasonable (glossary, principles, testability, relationships) and points to DEEPENING.md and DESIGN-IT-TWICE.md, but those references are described by repo-root paths rather than clearly signaled one-level-deep links, and no bundle files exist alongside SKILL.md to verify them.	3 / 5
	Total	13 / 20 Passed

Description

76%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 provides and when to use it, with a clear niche around deep-module design. The main weakness is trigger-term naturalness — several triggers are skill-specific jargon a user would not naturally voice.

Suggestions

Add natural-language trigger synonyms a user might actually say (e.g., 'refactor an interface,' 'reduce API surface,' 'make code easier to test') alongside the deep-module vocabulary.

Consider a brief user-facing phrasing of the 'when' clause that doesn't depend on knowing the term 'seam' or 'deep module' in advance.

Dimension	Reasoning	Score
Specificity	Lists several specific actions — 'design or improve a module's interface,' 'find deepening opportunities,' 'decide where a seam goes,' 'make code more testable or AI-navigable' — with only minor coverage gaps (e.g., no mention of reviewing/auditing existing modules).	4 / 5
Completeness	Clearly answers both what ('Shared vocabulary for designing deep modules') and when ('Use when the user wants to design or improve a module's interface, find deepening opportunities...'), with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes some relevant phrases ('design or improve a module's interface,' 'make code more testable,' 'deepening opportunities') but leans on jargon ('seam,' 'deep module') that a user is unlikely to say verbatim, missing common natural variations.	3 / 5
Distinctiveness Conflict Risk	Targets a fairly distinct niche (deep-module design vocabulary) with specific triggers; minor overlap risk with general refactoring or architecture skills.	4 / 5
	Total	16 / 20 Passed

Validation

100%

Warnings & errors only

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: windmill-labs/windmill
Path: .agents/skills/codebase-design/SKILL.md
Commit: 7915540

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.