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.
79
75%
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 specific deliverables, provides comprehensive trigger terms that users would naturally use, and explicitly separates the 'what' from the 'when'. The description is well-scoped to a distinct niche of pre-implementation technical design, making it unlikely to conflict with coding or general documentation skills.
| 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. | 3 / 3 |
Completeness | Clearly answers both what ('producing architecture diagrams, data models, API interface definitions, implementation plans, and multi-option trade-off analyses') and when ('Use when the user asks to plan a feature, architect a system, design an API...') with explicit trigger guidance and qualifying conditions. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms: 'plan a feature', 'architect a system', 'design an API', 'explore implementation approaches', 'technical design', 'spec before coding', 'complex features', 'architectural changes'. These are phrases users would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Occupies a clear niche: pre-coding technical design documents. The emphasis on 'before writing code' and the specific deliverables (architecture diagrams, trade-off analyses) distinguish it well from general coding skills or documentation skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable framework for design-first methodology with clear phasing and useful templates, but suffers from verbosity and generic guidance that Claude already understands. The content would benefit from being more concise, with stronger validation checkpoints and better separation of the overview from detailed reference material. The actionability is moderate — templates are helpful but much of the advice is standard software engineering wisdom rather than novel, specific instruction.
Suggestions
Cut generic design thinking advice Claude already knows (e.g., 'What exactly should this do?', 'What should it NOT do?', the 'Signals You Need More Design' section) to reduce token usage by ~30%.
Add explicit validation gates with concrete criteria — e.g., 'Design is ready when: all requirements have corresponding components, all error paths are documented, at least 2 options were evaluated' rather than soft self-review questions.
Move the Design Levels section and Anti-Patterns table into a separate reference file and link to it, keeping SKILL.md focused on the core workflow.
Provide a concrete, filled-out example of a completed mini design document (not just templates with placeholders) to make the skill more actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill contains some unnecessary content that Claude already knows (e.g., 'Think first, code second', generic questions like 'What exactly should this do?', signals like 'I'm not sure where to start'). The anti-patterns table and design levels section add moderate value but could be tighter. However, the templates and structured examples are useful additions. | 2 / 3 |
Actionability | The skill provides structured templates and markdown examples for design documents, option comparisons, and data models, which are somewhat actionable. However, much of the content is generic guidance rather than concrete, executable instructions — the templates are illustrative but not deeply specific to any real workflow, and the checklists are fairly standard design thinking prompts. | 2 / 3 |
Workflow Clarity | The four-phase process (Understand → Explore → Design → Validate) is clearly sequenced, and the integration with implementation section provides follow-through steps. However, validation checkpoints are weak — Phase 4 is a soft self-review checklist rather than explicit verification gates, and there's no feedback loop for what happens if validation fails beyond 'check against similar patterns.' | 2 / 3 |
Progressive Disclosure | The skill references a `DESIGN_TEMPLATE.md` file and a 'task-decomposition skill' which shows awareness of progressive disclosure. However, the main file is quite long (~150 lines of content) with sections like Design Levels and Anti-Patterns that could be split out. The reference to DESIGN_TEMPLATE.md is good but the template's contents are partially duplicated inline. | 2 / 3 |
Total | 8 / 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 | |
- Repository
- rohitg00/skillkit
- Commit
dfa8d12
- 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.