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
67%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./packages/core/src/methodology/packs/planning/design-first/SKILL.mdQuality
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.
| Dimension | Reasoning | Score |
|---|---|---|
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.
| Dimension | Reasoning | Score |
|---|---|---|
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.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
a9e5c83
Table of Contents
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.