Spec-Driven Development skill for Claude Code: write the spec before the code

Addy Osmani's skill that makes Claude write a spec you approve before it plans or codes, for new features and projects.

Installs: 69.7K; on skills.sh
Stars: 112.6K; on GitHub
Updated: Nov 2026; last repo commit

When you start a new project or feature, or the requirements are unclear, Claude writes a spec before any code. It first lists its assumptions, then covers six areas: objective, commands, project structure, code style, testing strategy and boundaries. Then it stops and waits for your approval in a later turn. The SKILL.md says: "Code without a spec is guessing."

After approval it moves to a plan, a task list and implementation, with a review gate between each. If one request bundles several separate capabilities, it first proposes a capability map of modules. It writes spec and plan files in your repo, such as tasks/plan.md. It bundles no scripts.

Good for

Developers starting a feature from a vague idea
Tech leads who want to review intent before code exists
Teams breaking a big request into modules

Install spec-driven-development

Claude Code

Copy this prompt.

Install the spec-driven-development skill in Claude Code. Run this command:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Spec-driven-development defers to planning-and-task-breakdown, incremental-implementation, test-driven-development and context-engineering, so install the whole pack.

From the project README. Source.

What's in the skill

When it loads

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when drafting a PRD or requirements document with objectives and scope, or when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying.

Sections in SKILL.md

Overview
When to Use
The Gated Workflow
Phase 0: Scope Check
Phase 1: Specify
Objective
Tech Stack
Commands
Project Structure
Code Style
Testing Strategy
Boundaries
Success Criteria
Open Questions
Phase 2: Plan
Phase 3: Tasks

Key facts

Author: addyosmani (agent-skills pack)
Repository: addyosmani/agent-skills
Installs on skills.sh: 69,707 (2 Nov 2026)
GitHub stars (repo): 112,555 (2 Nov 2026)
License: MIT
Last commit (repo): 1 Nov 2026
What installs: SKILL.md only (1 file); bundles no scripts. Defers to other skills in the same pack
Works in: Claude Code, Cursor, Codex, Copilot, Cline and more through the skills CLI; native Claude Code and Codex plugins
Needs: The rest of the agent-skills pack: its plan and implement phases defer to planning-and-task-breakdown, incremental-implementation and test-driven-development
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

Propose a capability map when a request bundles several capabilities
Claude lists modules with stable ids, dependencies and a build order for you to approve before any module spec is written.
Write · Phase 0: Scope check
List assumptions, then write the spec
Claude states its assumptions, covers objective, commands, project structure, code style, testing strategy and boundaries (always, ask first, never), saves the spec, and stops for your approval.
Try: “Write a spec for adding team invitations to my app.”
Write · Phase 1: Specify
Turn the approved spec into a technical plan
Claude identifies components, order, risks and checkpoints, and saves the plan to tasks/plan.md, following planning-and-task-breakdown.
Write · Phase 2: Plan
Break the plan into small, verifiable tasks
Each task has acceptance criteria and a verification step, and no task should touch more than about 5 files.
Write · Phase 3: Tasks
Build task by task
Claude follows incremental-implementation and test-driven-development, and loads only the spec sections it needs via context-engineering.
Runs code · Phase 4: Implement
Update the spec first when decisions change
The spec is committed with the code and referenced in pull requests.
Write · Keep the spec alive

From the official docs

Permissions

Low risk

The skill writes spec and plan files into your repo and, after you approve, helps edit code. Work on a branch and review each phase before you approve the next.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It creates files in your repo
The spec and plan are saved as files such as tasks/plan.md and a spec file at the project root. Check git status and commit them on purpose.

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	The skill defines no read-only switch.
Scopes	Claude writes spec files, a capability map and tasks/plan.md in your repo In the implement phase Claude edits code and runs your tests and build commands

Questions

What does the Spec-Driven Development skill do?

It makes Claude write a structured spec and get your approval before it plans or builds. The spec covers the goal, commands, structure, style, tests and boundaries, so misunderstandings show up before code exists.

How do I install it?

Use the install box at the top of this page. It installs the whole agent-skills pack, because this skill hands the plan and build phases to sibling skills in the same pack. Restart your agent session afterwards.

Will Claude start coding straight away?

No. After it saves the spec it must summarize it, list open questions and stop. The SKILL.md says planning starts only after you approve the spec in a later turn.

When should I skip it?

For single-line fixes, typo corrections, or changes where requirements are already clear and self-contained, according to the SKILL.md. A two-line spec is fine for simple tasks.

Spec-Driven Development vs interview-me?

Spec-driven-development writes the spec. The same pack has a separate interview-me skill that asks one question at a time to pull requirements out of an underspecified request. The README describes it as an interview until about 95% confidence.

Does it work in Cursor, Codex or Copilot?

Yes. The README documents a Codex plugin, the skills CLI for 70+ agents including Cursor, and manual setup for Cursor and Copilot. The slash commands (/spec, /plan, /build and so on) are Claude Code commands and do not appear in Copilot, where you invoke skills by name. The README does not describe a Claude app install.

Is it safe to install?

It is low risk. It is instructions with no scripts, but it makes Claude write spec and plan files in your repo and later edit code. Review the spec before you approve it, and commit work on a branch.

Information

updated Nov 2, 2026

Repository: addyosmani/agent-skills
Folder: skills/spec-driven-development

addyosmani/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

addyosmani/agent-skills README · github.com
spec-driven-development SKILL.md · github.com