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.

Quality

63%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

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

Quality

Content

27%

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 explains many concepts Claude already understands. While it provides useful structure (phases, templates, option comparison format), it suffers from excessive length, broken file references, and generic examples that don't add much beyond what Claude would naturally produce. The content would benefit significantly from aggressive trimming and proper use of bundle files for detailed templates and examples.

Suggestions

Cut the content by 50-60% — remove sections like 'Signals You Need More Design', 'Questions to Ask', and 'Anti-Patterns to Avoid' which describe concepts Claude already knows. Focus on the specific output format and template structure you want.

Create and include the referenced DESIGN_TEMPLATE.md as a bundle file, and move the detailed template content there. The SKILL.md should be a concise overview pointing to the template.

Replace the generic Order/OrderService examples with a note that examples should be domain-relevant, or remove them entirely — Claude knows how to write TypeScript interfaces and doesn't need a demonstration.

Add explicit validation checkpoints between phases, such as 'Do not proceed to Phase 3 until the user has confirmed requirements' and 'Present the design document to the user for approval before breaking into implementation tasks.'

Dimension	Reasoning	Score
Conciseness	The skill is verbose and explains many concepts Claude already knows well — what design-first means, when to use it, questions to ask, what edge cases are, rubber duck debugging, etc. Much of this is general software engineering knowledge that doesn't need to be spelled out. The 'Signals You Need More Design' section and 'Questions to Ask' section are particularly redundant for Claude.	1 / 3
Actionability	The skill 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 instructive — it tells Claude what a design document should contain but the examples are generic placeholders (Order/OrderService) rather than executable guidance. The template reference to DESIGN_TEMPLATE.md is not provided.	2 / 3
Workflow Clarity	The four phases provide a clear sequence, and Phase 4 includes validation steps. However, there are no explicit checkpoints between phases, no feedback loops for when validation fails (just 'validate' without clear recovery steps), and the integration with implementation section is vague. The transition from design to implementation lacks concrete verification gates.	2 / 3
Progressive Disclosure	The skill references DESIGN_TEMPLATE.md but no bundle files are provided, making this a broken reference. The content is monolithic — over 150 lines of inline content that could be split into the template file and a more concise overview. The three design levels section, anti-patterns table, and detailed phase content all bloat the main file when they could be referenced separately.	1 / 3
	Total	6 / 12 Passed

Description

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 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 pre-coding design work, making it highly distinguishable from related skills like code generation or general documentation.

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 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 are highly natural phrases.	3 / 3
Distinctiveness Conflict Risk	Clearly scoped to pre-coding technical design documents with distinct triggers like 'technical design', 'spec before coding', and 'architecture'. The emphasis on planning before implementation distinguishes it from coding or documentation skills.	3 / 3
	Total	12 / 12 Passed

Validation

90%

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 — 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: d2e5c34

Reviewed: 12 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.