spec-driven-development
by addyosmanispec-driven-development is a workflow skill for writing specs before code, then moving through planning, tasks, and implementation with human review at each phase.
This skill scores 74/100, which is a solid-but-not-top-tier listing candidate. For directory users, that means it is genuinely useful for agents that need a spec-first workflow, with enough structure to reduce guesswork, but it still lacks supporting files and packaged guidance that would make adoption frictionless.
- Clear trigger guidance: use when starting a new project, feature, or ambiguous change, and explicitly not for trivial fixes.
- Strong operational workflow: four gated phases (Specify → Plan → Tasks → Implement) with human review at each step.
- Good practical depth: substantial SKILL.md content with multiple headings, constraints, and code examples, making the process easier for an agent to follow.
- No support files or install command: adoption depends almost entirely on the SKILL.md instructions.
- Single-file delivery: no scripts, references, or resources to reinforce the workflow or handle edge cases.
Overview of spec-driven-development skill
spec-driven-development is a workflow skill for writing a clear spec before code, then using that spec to guide planning, tasks, and implementation. It is best for the spec-driven-development skill when you are starting a new feature, changing architecture, or working from vague requirements and need fewer assumptions in the final build.
What this skill is for
Use this spec-driven-development guide when the main risk is building the wrong thing, not just building it poorly. It helps you turn a rough idea into a shared source of truth that defines scope, behavior, constraints, and acceptance criteria before you commit to implementation.
Best-fit adoption cases
This skill fits teams and solo builders who want tighter alignment with a human reviewer, especially when a task crosses files, depends on product decisions, or is large enough that “just code it” creates rework. It is also useful for spec-driven-development for Skill Authoring when you want the skill itself to generate disciplined, reviewable outputs.
What makes it different
The value is the gated workflow: specify, then plan, then tasks, then implement, with human review at each step. That makes it stronger than a generic prompt because it reduces hidden assumptions and forces decision points earlier, when changes are cheaper.
How to Use spec-driven-development skill
Install and load context
For spec-driven-development install, add the skill to your agent skills setup and then open the skill file first:
npx skills add addyosmani/agent-skills --skill spec-driven-development
Then read SKILL.md before anything else. This repository does not include supporting folders like rules/, references/, or scripts/, so the skill context lives almost entirely in the main skill file.
Give the skill a concrete starting point
The spec-driven-development usage pattern works best when you provide a goal, constraints, and known unknowns. Weak input looks like “build a dashboard.” Strong input looks like:
“Create a spec for a dashboard that shows subscription health, supports role-based access, and must work with our existing REST API. Ask clarifying questions before drafting the spec. Do not propose implementation details yet.”
That gives the skill enough context to surface assumptions and avoid premature design.
Follow the gated workflow
The skill is designed to stop at each phase until validated. In practice, that means:
- Specify the problem and assumptions.
- Plan the approach after the spec is approved.
- Break the plan into tasks.
- Implement only after task review.
If you skip review gates, you lose the main benefit of the skill: fewer reworks caused by untested assumptions.
Read first and use next
Start with SKILL.md, then use the sections on overview, when to use, and the gated workflow as your operating rules. If you are adapting this for your own agent flow, preserve the review checkpoints and the “ask until concrete” behavior, because those are the parts most likely to improve output quality.
spec-driven-development skill FAQ
Is spec-driven-development better than a normal prompt?
Usually yes when the task is ambiguous, cross-cutting, or expensive to redo. A normal prompt can produce code quickly, but spec-driven-development is better when you need agreement on what to build before anyone starts coding.
When should I not use it?
Do not use the spec-driven-development skill for trivial edits, obvious bug fixes, or self-contained changes with no real product ambiguity. In those cases, the overhead of a full spec cycle can be slower than the work itself.
Is this beginner-friendly?
Yes, if you are willing to answer clarifying questions and review drafts. The skill is easier to use than inventing your own process because it tells the agent to pause, surface assumptions, and move through phases in order.
Does it fit Skill Authoring workflows?
Yes, especially for spec-driven-development for Skill Authoring when you want a repeatable process for writing a new skill or upgrading an existing one. It is most useful when the authoring task needs clear scope, review gates, and a spec that can be validated before implementation.
How to Improve spec-driven-development skill
Provide sharper inputs up front
The strongest results come from stating the target user, desired outcome, constraints, and what is still unknown. For example: “Migrate the checkout flow without changing the public API, preserve existing analytics events, and identify any dependency risks before planning.”
Force the skill to name assumptions
One common failure mode is vague specs that sound complete but hide critical decisions. Ask the model to list assumptions before drafting the spec, then review those assumptions with the human engineer before moving to planning. That is where spec-driven-development usually saves the most time.
Iterate on the spec, not the code
If the first pass is off, correct scope, acceptance criteria, or constraints before asking for implementation. The workflow works best when each revision tightens the contract, because later phases depend on the precision of the spec.
Use it when reviews are expensive
The skill is most valuable when bad assumptions would be costly: multi-file changes, architecture shifts, or features that affect multiple stakeholders. If the first draft of your spec is still fuzzy, keep it in the spec phase longer rather than forcing tasks or code too early.