CtrlK
BlogDocsLog inGet started
Tessl Logo

design-first

Guides the creation of technical design documents before writing code, producing architecture diagrams, data models, API interface definitions, implementation plans, and multi-option trade-off analyses. Use when the user asks to plan a feature, architect a system, design an API, explore implementation approaches, or requests a technical design or spec before coding — especially for complex features involving multiple components, ambiguous requirements, or significant architectural changes.

73

Quality

67%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./packages/core/src/methodology/packs/planning/design-first/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

100%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a strong skill description that clearly articulates what the skill produces (design documents, architecture diagrams, data models, API definitions, implementation plans, trade-off analyses) and when to use it (planning features, architecting systems, designing APIs, exploring approaches before coding). It uses third person voice consistently, includes natural trigger terms, and carves out a distinct niche focused on pre-implementation technical planning.

DimensionReasoningScore

Specificity

Lists multiple specific concrete actions: 'architecture diagrams, data models, API interface definitions, implementation plans, and multi-option trade-off analyses.' These are clearly defined deliverables, not vague language.

3 / 3

Completeness

Clearly answers both 'what' (producing architecture diagrams, data models, API definitions, implementation plans, trade-off analyses) and 'when' with an explicit 'Use when...' clause listing multiple trigger scenarios, plus additional context about when it's especially relevant.

3 / 3

Trigger Term Quality

Excellent coverage of natural terms users would say: 'plan a feature', 'architect a system', 'design an API', 'explore implementation approaches', 'technical design', 'spec before coding', 'complex features', 'architectural changes'. These closely match how users naturally phrase such requests.

3 / 3

Distinctiveness Conflict Risk

Occupies a clear niche: pre-coding technical design and planning. The emphasis on 'before writing code' and specific deliverables like 'trade-off analyses' and 'architecture diagrams' distinguish it well from general coding skills, documentation skills, or API implementation skills.

3 / 3

Total

12

/

12

Passed

Implementation

35%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill is a comprehensive but overly verbose guide to design-first methodology that reads more like a developer handbook than a concise skill for Claude. Its strengths are the structured phases and useful templates (option comparison, design document outline), but it suffers from explaining concepts Claude already understands, lacks concrete validation checkpoints between phases, and references a template file that doesn't exist in the bundle.

Suggestions

Cut at least 40% of content by removing sections Claude already knows (e.g., 'Questions to Ask', 'Signals You Need More Design', explanations of what design levels are) and focus only on the specific templates and output formats Claude should produce.

Add explicit phase-gate criteria — e.g., 'Do not proceed to Phase 3 until the user has confirmed requirements' or 'Present options to user and wait for selection before designing' — to create real validation checkpoints.

Either include the referenced DESIGN_TEMPLATE.md as a bundle file or inline the template directly; a broken reference undermines the skill's utility.

Replace generic placeholder examples (Order, OrderService) with a more concise indication that Claude should adapt to the user's actual domain, or remove them entirely since Claude knows how to write TypeScript interfaces.

DimensionReasoningScore

Conciseness

Significant verbosity throughout. Sections like 'Questions to Ask' and 'Signals You Need More Design' explain things Claude already knows. The 'When to Use Design First' list is obvious. Much of the content reads like a tutorial for a junior developer rather than concise instructions for an AI assistant.

1 / 3

Actionability

Provides templates and structured formats (option comparison markdown, design document sections, data model examples) which are somewhat actionable. However, much of the content is descriptive rather than prescriptive — it tells Claude what a design document should contain conceptually but the examples are generic placeholders rather than executable guidance tied to specific tool usage or concrete outputs.

2 / 3

Workflow Clarity

The four-phase process (Understand → Explore → Design → Validate) provides a clear sequence, and the 'Integration with Implementation' section adds post-design steps. However, there are no explicit validation checkpoints between phases — no criteria for when Phase 1 is 'done enough' to proceed, and the validation phase is a soft self-review checklist rather than a concrete verification step with feedback loops.

2 / 3

Progressive Disclosure

References DESIGN_TEMPLATE.md but no bundle file is provided, so the reference is broken. The skill itself is monolithic — the design levels section, anti-patterns table, and detailed phase content could be split into referenced files. The structure within the single file is reasonable with clear headings, but too much is inlined.

2 / 3

Total

7

/

12

Passed

Validation

90%

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

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

10

/

11

Passed

Repository
rohitg00/skillkit
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.