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.
66
79%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/spec-driven-development/SKILL.mdQuality
Discovery
82%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 solid description with excellent completeness and trigger term coverage, clearly stating both what the skill does and when to use it. Its main weaknesses are a lack of specificity about what kind of specs are created and what the output looks like, and some potential overlap with related planning/requirements skills.
Suggestions
Add specific concrete actions to improve specificity, e.g., 'Creates specs before coding: gathers requirements, defines acceptance criteria, outlines architecture decisions, and produces a structured specification document.'
Differentiate from related skills by specifying the type of specs (e.g., 'software feature specifications' vs API specs, test specs) to reduce conflict risk.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (specs/specifications) and the core 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 actions are not comprehensively listed. | 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). Explicit 'Use when' clauses are present with multiple trigger scenarios. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'specs', 'new project', 'feature', 'significant change', 'specification', 'requirements', 'unclear', 'ambiguous', 'vague idea'. These are terms users would naturally use when they need help creating a specification before coding. | 3 / 3 |
Distinctiveness Conflict Risk | While 'specs before coding' is a reasonably distinct niche, it could overlap with project planning, requirements gathering, or architecture design skills. The term 'specification' is somewhat broad and could conflict with API spec generation or test spec skills. | 2 / 3 |
Total | 10 / 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, highly actionable skill that clearly defines a gated workflow for spec-driven development with concrete templates and examples. Its main weakness is moderate verbosity — the 'Common Rationalizations' table and 'Red Flags' section add motivational content that Claude doesn't need, and the overall length could be reduced by extracting detailed templates into bundle files. The workflow clarity is excellent with explicit human review gates at each phase.
Suggestions
Remove or significantly trim the 'Common Rationalizations' table and 'Red Flags' section — these explain *why* to use specs, which Claude doesn't need; the skill should focus on *how*.
Consider extracting the detailed spec template and task template into a separate TEMPLATES.md bundle file, keeping only a brief summary in the main SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably well-structured 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 valuable and earn their tokens. | 2 / 3 |
Actionability | The skill provides concrete, copy-paste-ready templates for specs, tasks, and assumptions. The spec template with all six core areas, the task template with acceptance criteria and verification steps, and the reframing example (vague requirement → concrete success criteria) are all highly actionable and specific. | 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 outputs and validation checkpoints, and 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 progressive disclosure. However, the skill itself is quite long (~150 lines of substantive content) and could benefit from splitting the spec template, common rationalizations, or detailed phase descriptions into separate reference files. With no bundle files, everything is inline. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%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
f17c6e8
- 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.