Guide · Agent skill
How to use the Spec-Driven Development agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The spec-driven-development skill tells an AI coding agent to write a structured specification before it writes code. It is for developers starting a new project or a larger feature, teams drafting a PRD, and anyone whose requirements are still vague. After this guide you will know what the skill does, how to install it, how to trigger it with a normal request, and where its limits are.
Spec-Driven Developmentaddyosmani/agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project.
- 3Or upload in the Claude apps. In the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill.
- 4Describe your project in plain language. Explain what you want to build and why, and say if the requirements are unclear or bundle several capabilities.
- 5Review the assumptions and spec. Correct any wrong assumptions the agent lists, then review the drafted spec and its open questions.
- 6Approve before planning. Approve the spec or request changes. Planning and code begin only after your approval.
What the skill makes the agent do
When you ask for a new project, feature, or significant change, the agent first drafts a written specification. The spec covers the objective, commands, project structure, code style, testing approach, and boundaries. The spec is meant to be the shared source of truth between you and the agent, defining what is being built, why, and how completion will be judged.
The agent pauses for your review at each stage before it writes code. Its surfaced assumptions are listed for you to correct, so wrong guesses are caught before code exists.
- Objective: what is being built, why, and what success looks like
- Commands: full executable build, test, lint, and dev commands
- Project structure: where source, tests, and docs live
- Code style: a real snippet plus naming and formatting rules
- Testing strategy: framework, test locations, and test levels
- Boundaries: actions the agent should always take, ask first on, or never take
Install the spec-driven-development skill
Download the ZIP file for the skill from this page. Unzip it into one of two places. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.
If you use the Claude apps instead, you can upload the skill under Settings, then Capabilities, then Skills. The skill package contains one file, SKILL.md, and lists no required tools or packages.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with a natural request
You do not need a special command. The skill's description tells the agent when to use it, so describe your situation in plain language. The skill activates when you are starting something new, when you want a PRD or requirements document with objectives and scope, when requirements are unclear or only exist as a vague idea, or when one requirement contains several separately testable capabilities.
If your request bundles several separate capabilities, the agent first proposes a capability map: a small table of modules, their dependencies, and a build order. You approve the map before any module spec is written.
- 'I want to start a new project for a booking app. Write a spec before we code.'
- 'Draft a PRD for adding team invitations, with objectives and scope.'
- 'The requirement is just to make onboarding better. Help me pin down what that means.'
- 'This feature covers accounts, billing, and notifications. Break it into modules first.'
What to expect during the workflow
The workflow has four phases: Specify, Plan, Tasks, and Implement. Each phase waits for your review before the next starts. Before writing the spec, the agent lists its assumptions and asks you to correct them. It also turns vague goals into concrete success criteria, such as a measurable load-time target, and asks whether those targets are right.
After the spec is saved, the agent summarizes it, lists open questions, and asks for approval. It stops there. Planning begins only in a later turn, after you approve.
- Assumptions are listed first, so you can correct them early
- Vague goals are rewritten as testable success criteria
- The agent stops after the spec and waits for your approval
- Small fixes and single-file changes are outside this skill's scope
Limits, safety, and tips
The skill runs no scripts and makes no network calls, according to its listing. It requires nothing beyond the skill file itself. Its main cost is time: the workflow deliberately pauses for human review at every phase, so it is not suited to a project you want finished unattended.
If your project already uses OpenSpec or another specification system, the skill is designed to keep that tool's format and storage instead of creating a duplicate SPEC.md. Keep requests specific so the agent has less to guess about.
- Runs scripts: no. Uses network: no. Requires: nothing listed.
- Skip it for typos, small fixes, and clearly defined single-file changes.
- Answer the assumption list carefully, since those answers shape the spec.
- Use the capability map for multi-capability requests so each module gets its own spec, named by module id.
What people use it for
- Starting a new web application and settling the stack, commands, and boundaries before any code is written.
- Drafting a PRD with objectives and scope for a feature that a team needs to agree on.
- Turning a vague goal such as making a dashboard faster into measurable success criteria.
- Splitting a large initiative into modules like identity, billing, and notifications with a reviewed build order.
Frequently asked questions
Is the spec-driven-development skill free to use?
The skill is published under the MIT licence, as listed on this page. The listing does not mention any price, so check the source page for any current terms before relying on it.
What do I need to run this skill?
The listing lists no requirements. It runs no scripts and makes no network calls. You need an agent environment that can load skills, such as the Claude apps or a Claude setup that reads a skills folder.
Where do I install the skill?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use, or into .claude/skills/ in a project. In the Claude apps, upload it under Settings, Capabilities, Skills.
Why does the agent keep stopping and asking me questions?
The workflow is built to pause for human review at each phase, and to surface wrong assumptions before code is written. If you want the agent to finish without stopping, this skill is the wrong fit.
Should I use this skill for small bug fixes?
No. The skill says not to use it for single-line fixes, typo corrections, or changes with unambiguous, self-contained requirements, because it would only add overhead.
Does this skill work with OpenSpec or other spec tools?
Yes. If your project already uses OpenSpec or another specification system, the skill keeps that tool's artifact format and storage conventions instead of creating a duplicate SPEC.md.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers starting a new project or larger feature, and teams drafting PRDs who want requirements settled before coding. It is a poor fit for small fixes, or for anyone who wants an agent to finish a whole project unattended, since it deliberately stops for review at every phase.
Download the skill