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.

1.90x

Quality

—

Does it follow best practices?

Impact

95%

1.90x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, highly actionable workflow skill with clear gated phases and verification. Its main gaps are motivational padding that hurts token efficiency and a monolithic single-file layout with no internal reference split.

Suggestions

Trim or remove the 'Common Rationalizations' table and 'Red Flags' section; they coach the user rather than instruct Claude.

Split the spec template and task template into a references/ file (e.g. references/spec-template.md) and link to it, moving toward an overview-plus-details structure.

Condense rhetorical lines like "Code without a spec is guessing" and "Waterfall in 15 minutes beats debugging in 15 hours" into terse guidance.

Dimension	Reasoning	Score
Conciseness	The core is efficient with real templates, but the 'Common Rationalizations' table, 'Red Flags' list, and rhetorical flourishes ("Code without a spec is guessing") are motivational padding rather than actionable guidance; not a 3 because not every token earns its place.	2 / 3
Actionability	Copy-paste-ready markdown spec and task templates, concrete commands ("npm run build", "npm test -- --coverage"), and worked examples (assumptions, success-criteria reframing) give fully executable guidance.	3 / 3
Workflow Clarity	A clear four-phase sequence with an explicit gate ("Do not advance… until the current one is validated"), human-review checkpoints between phases, and a final verification checklist; not a 2 because validation checkpoints are explicit, not implicit.	3 / 3
Progressive Disclosure	No bundle files exist and the ~207-line SKILL.md is monolithic, with templates and the rationalizations table kept inline; cross-skill references are well signaled but are not in-skill bundle files, so it is not the anchor-3 'overview pointing to detailed materials'.	2 / 3
	Total	10 / 12 Passed

Description

90%

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

A strong description: concrete action, explicit dual 'Use when' triggers, and natural trigger terms. Its only weakness is naming a single action rather than enumerating the skill's several concrete capabilities.

Suggestions

Expand the capability clause beyond one action, e.g. 'Creates specs before coding — surfaces assumptions, defines success criteria, and breaks work into gated phases.'

Dimension	Reasoning	Score
Specificity	Quotes a single concrete action — "Creates specs before coding" — and names the domain, but does not list multiple distinct actions (e.g. surfacing assumptions, defining success criteria), so it stops short of the anchor-3 'lists multiple specific concrete actions'.	2 / 3
Completeness	It states what ("Creates specs before coding") and gives two explicit 'Use when…' trigger clauses, answering both what and when; not a 2 because 'when' is explicit rather than implied.	3 / 3
Trigger Term Quality	Natural user phrasing is well covered: "starting a new project, feature", "requirements are unclear, ambiguous", and "only exist as a vague idea" are all things a user would actually say.	3 / 3
Distinctiveness Conflict Risk	The spec-before-coding framing plus triggers tied to missing/ambiguous requirements carve a clear niche unlikely to fire for unrelated skills.	3 / 3
	Total	11 / 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: addyosmani/agent-skills
Commit: 70b7506

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