spec-driven-development

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.

Quality

72%

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 ./skills/spec-driven-development/SKILL.md

Quality

Content

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 strong, well-structured skill that provides a clear gated workflow with concrete templates and examples. Its main weakness is verbosity — the 'Common Rationalizations' and 'Red Flags' sections add ~30 lines of content that teaches Claude things it already knows about software development best practices. The actionability and workflow clarity are excellent, with specific templates, validation checkpoints, and human review gates at each phase.

Suggestions

Remove or significantly condense the 'Common Rationalizations' table and 'Red Flags' section — Claude already understands why specs are valuable; these sections consume tokens without adding actionable guidance.

Consider extracting the full spec template into a separate SPEC_TEMPLATE.md file and referencing it, keeping only a brief summary in the main SKILL.md to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The skill is generally well-written but includes some unnecessary content. The 'Common Rationalizations' table and 'Red Flags' section explain things Claude already understands about why specs matter. The 'When NOT to use' section and some of the rationale text could be trimmed. However, the templates and examples are efficient and earn their place.	2 / 3
Actionability	The skill provides concrete, copy-paste-ready templates for specs, tasks, and assumptions. The examples are specific (e.g., the dashboard performance reframing, the assumptions block, the task template with acceptance criteria and verification steps). The six core areas are well-defined with executable command examples and directory structures.	3 / 3
Workflow Clarity	The four-phase gated workflow (Specify → Plan → Tasks → Implement) is clearly sequenced with explicit human review gates between each phase. The ASCII diagram reinforces the flow. Each phase has clear deliverables and validation checkpoints. The verification checklist at the end provides a final gate before implementation.	3 / 3
Progressive Disclosure	The skill references other skills (incremental-implementation, test-driven-development, context-engineering) appropriately in Phase 4, which is good. However, the content is quite long (~150+ lines) and could benefit from splitting the spec template, task template, and common rationalizations into separate reference files. The monolithic structure makes it harder to navigate, though the section headers help.	2 / 3
	Total	10 / 12 Passed

Description

67%

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

The description has strong completeness with explicit 'Use when' triggers covering multiple scenarios, which is its greatest strength. However, it lacks specificity about what the spec creation actually entails (e.g., user stories, acceptance criteria, architecture decisions) and could benefit from more varied trigger terms to cover how users naturally refer to specifications and planning documents.

Suggestions

Add specific concrete actions the skill performs, e.g., 'Creates specs including requirements, acceptance criteria, technical approach, and scope definitions before coding.'

Expand trigger terms to include common variations like 'PRD', 'design doc', 'technical spec', 'RFC', 'planning document', or 'requirements document'.

Dimension	Reasoning	Score
Specificity	The description names the domain (specs/specifications) and the action (creates specs before coding), but lacks detail on what specific actions are involved—e.g., does it generate requirement documents, user stories, architecture diagrams, acceptance criteria? The concrete actions are not enumerated.	2 / 3
Completeness	Clearly answers both 'what' (creates specs before coding) and 'when' (starting a new project/feature/significant change with no spec, or when requirements are unclear/ambiguous/vague). The 'Use when' clauses are explicit and well-articulated.	3 / 3
Trigger Term Quality	Includes some natural terms like 'new project', 'feature', 'specification', 'requirements', and 'vague idea', which users might say. However, it misses common variations like 'spec doc', 'PRD', 'product requirements', 'design doc', 'technical spec', 'RFC', or 'planning'.	2 / 3
Distinctiveness Conflict Risk	The skill is somewhat specific to specification creation, but terms like 'new project', 'feature', and 'significant change' could overlap with project scaffolding, planning, or architecture skills. The niche is identifiable but not sharply delineated from related planning/design skills.	2 / 3
	Total	9 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: addyosmani/agent-skills
Commit: 5e262b2

Reviewed: 1 day 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.