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.
90
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 an excellent skill description that hits all the marks. It provides specific concrete outputs, includes a comprehensive 'Use when...' clause with natural trigger terms users would actually say, and clearly distinguishes itself as a pre-coding planning skill. The description is well-structured, uses proper third-person voice, and provides enough context for Claude to confidently select this skill when appropriate.
| 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 all distinct, actionable outputs. | 3 / 3 |
Completeness | Clearly answers both what (creating technical design documents with specific outputs) AND when (explicit 'Use when...' clause with multiple trigger scenarios including feature planning, system architecture, API design, and conditions like 'complex features' or 'ambiguous requirements'). | 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'. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused on pre-coding design and planning phase with distinct triggers like 'before writing code', 'technical design or spec before coding' - unlikely to conflict with coding skills or documentation skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured skill with strong actionability and clear workflow sequencing. The concrete templates, checklists, and examples make it immediately usable. However, it could be more concise by trimming explanatory content Claude already understands, and some detailed sections could be moved to referenced files for better progressive disclosure.
Suggestions
Remove explanatory phrases like 'Think first, code second' and 'Rubber duck explanation (explain to yourself/others)' that explain concepts Claude already knows
Consider moving the detailed 'Design Levels' and 'Anti-Patterns' sections to a separate reference file to reduce the main skill's length
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is reasonably efficient but includes some unnecessary explanation that Claude would already know (e.g., explaining what 'rubber duck explanation' means, basic concepts like 'think first, code second'). Some sections could be tightened without losing clarity. | 2 / 3 |
Actionability | Provides concrete, actionable templates with specific markdown formats, TypeScript interface examples, ASCII diagrams, and checklists. The design document template reference and structured phases give Claude clear, executable guidance. | 3 / 3 |
Workflow Clarity | Clear four-phase process with explicit validation in Phase 4. The workflow includes self-review checklist, external validation steps, and explicit guidance on when to stop and design more. The integration section provides clear sequencing for transitioning to implementation. | 3 / 3 |
Progressive Disclosure | References DESIGN_TEMPLATE.md appropriately for detailed artifact structure, but the main document itself is quite long with content that could potentially be split (e.g., the detailed option evaluation template, anti-patterns table). The structure is good but borders on monolithic. | 2 / 3 |
Total | 10 / 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 | |
- 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.