Source: addyosmani/agent-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 24 October 2026
What is the spec-driven-development skill?
The spec-driven-development skill makes Claude Code and other coding agents write a specification before any code: list assumptions, answer clarifying questions, cover six fixed areas, then stop and wait for your approval. It is for developers who want an agent to agree on what "done" means before it touches files.
It comes from addyosmani/agent-skills, Addy Osmani's MIT-licensed set of 25 engineering skills, where it sits in the DEFINE stage of the repo's DEFINE, PLAN, BUILD, VERIFY, REVIEW, SHIP lifecycle. The skill's description reads: "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."
It is the fifth most installed skill in the repo. As of 24 October 2026, its skills.sh page listed 63.7K installs (snapshot, 24 October 2026), with Pass results from all three security audits shown (Gen Agent Trust Hub, Socket and Snyk).
What does it do?
The SKILL.md sets out a gated workflow: Specify, Plan, Tasks, Implement, with a human review after each phase. Its overview puts it bluntly: "Code without a spec is guessing."
Phase 0: scope check. Most requests skip this. It applies only when one request bundles several independently testable capabilities, such as identity, billing and notifications. The agent then proposes a short capability map first: a table of module ids, responsibilities and dependencies, plus a build order. Module ids are kebab-case and never renamed, dependencies point one way, and you approve the map before any module spec is written.
Phase 1: specify. The agent asks clarifying questions and lists its assumptions up front ("Correct me now or I'll proceed with these"). Then it writes a spec covering six core areas:
| Area | What goes in it |
|---|---|
| Objective | What you're building, why, for whom, and what success looks like |
| Commands | Full build, test, lint and dev commands with flags |
| Project structure | Where source, tests and docs live |
| Code style | One real code snippet plus naming and formatting rules |
| Testing strategy | Framework, test locations, coverage, which test levels for what |
| Boundaries | Always do, ask first, never do |
The template adds Tech Stack, Success Criteria and Open Questions sections. Vague requests get reframed as testable criteria: "make the dashboard faster" becomes targets like LCP under 2.5s and CLS under 0.1, which the agent then asks you to confirm.
Then comes the rule that shapes the whole experience. After saving the spec, the agent summarizes it, lists open questions, asks for approval and must "STOP YOUR TURN IMMEDIATELY." It may not start planning or write code in the same turn.
Phases 2 to 4. After approval, the agent writes a plan to tasks/plan.md, breaks it into tasks in tasks/todo.md (each with acceptance criteria, a verification step, and no more than about five files), and implements one task at a time with the repo's incremental-implementation and test-driven-development skills. For planning details it defers to planning-and-task-breakdown, which it calls "the canonical source."
The spec stays alive: update it before implementing a changed decision, commit it, and link spec sections from PRs. A rationalizations table answers excuses like "This is simple, I don't need a spec" with "A two-line spec is fine."
What's in the folder: only SKILL.md. Unlike some skills in the repo, it links to no shared references/ file, so a single-skill install loses nothing from the skill itself.
How do you install the spec-driven development skill?
Whole set as a Claude Code plugin. From the README:
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
This adds every skill plus nine slash commands, including /spec, /plan and /build. Plugin skills are namespaced as /plugin-name:skill-name per the Claude Code skills docs, so the skill itself is /agent-skills:spec-driven-development. If the marketplace step fails over SSH, the README gives an HTTPS form: /plugin marketplace add https://github.com/addyosmani/agent-skills.git.
Just this skill. The command on skills.sh, using the skills CLI:
npx skills add https://github.com/addyosmani/agent-skills --skill spec-driven-development
Add -g for all projects. The folder lands in .claude/skills/spec-driven-development/, or ~/.claude/skills/spec-driven-development/ with -g. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills. The README says that in Codex, installed as a plugin, you call skills with @, for example @spec-driven-development.
The README warns that a per-skill npx install "copies only skills/<name>/, not the repo-level references/ directory." This skill doesn't use those files, but it does point to sibling skills (planning-and-task-breakdown, incremental-implementation, test-driven-development, context-engineering). If you install it alone, install those too with more --skill flags, or use the plugin.
How do you use it?
With the plugin, type /spec and describe what you want. The command file asks the agent to clarify the objective and users, core features and acceptance criteria, tech stack, and boundaries, then save the spec as SPEC.md in the project root and confirm with you before going further. Without the plugin, the skill can load on its own when you start a new feature or give a vague request.
Example prompts (suggestions, not quotes from the repo):
/spec A CSV import for customer records: upload, preview, map columns, import.Use the spec-driven-development skill. I want a team billing page but I haven't decided on seats versus usage pricing.We need accounts, billing, email notifications and usage reports for the new product. Start with a capability map.Make search faster. Before anything else, turn that into success criteria I can approve.
Expect the first reply to be questions and a list of assumptions, not a document. After you approve the spec, run /plan (or ask for a plan), then /build to implement one task at a time. The README describes /build auto as a mode that "generates the plan and implements every task in a single approved pass"; its command file says it only runs when a spec exists at SPEC.md, docs/SPEC.md or under spec/.
Requirements: none beyond a repo the agent can write to. There are no scripts, packages or API keys.
How does it compare with similar skills?
Several popular skills cover the "think before coding" step, with different outputs.
| Skill | Output | Gate |
|---|---|---|
addyosmani spec-driven-development |
SPEC.md with six fixed areas, optional capability map | Stops after the spec; each later phase reviewed too |
| Superpowers brainstorming | A written design doc, reached one question at a time | Nothing is built until you approve the design doc |
| mattpocock grill-me | No file; a clearer plan from rounds of questions | Ends when every decision is settled and you confirm |
If you want a fixed document format your team can review and commit, this skill's six-area template gives you one. If you mainly want the agent to question you, grill-me writes nothing and only sharpens the idea. addyosmani/agent-skills also has its own interview-me skill for one-question-at-a-time interviews.
Tips and limits
From the files, not from testing:
- It will stop. The spec turn ends with a question, by design. If you want fewer stops after the spec is approved, the repo's
/build automode keeps one approval for the plan. - Keep your spec tool. If you already use OpenSpec or a similar system, the skill says to keep that format and not create a duplicate
SPEC.md. - It writes files. Expect
SPEC.md(or module specs), thentasks/plan.mdandtasks/todo.mdin later phases. Commit them or add them to.gitignoreas your team prefers. - Small jobs don't need it. The skill excludes single-line fixes, typos and self-contained changes. If it triggers on small work, say "skip the spec."
- No scripts. It runs nothing on its own.
- License. MIT, so you can fork it and change the template as long as you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md; for a repo with many skills it shows a list to pick from, so you can take planning-and-task-breakdown and the other skills it hands off to in one go. You can also drop a folder or a .zip, which is handy if you edit the spec template for your team first. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Addy Osmani or addyosmani/agent-skills.
Similar skills
- Planning and task breakdown skill: the next step, turning an approved spec into ordered tasks.
- Brainstorming skill: Superpowers' question-first design step.
- Grill me skill: Matt Pocock's interview until every decision is settled.
- Writing plans skill: Superpowers' spec-to-plan skill.