Chapter 2 · Spec-Driven Development in Depth · Lesson 2.4

OpenSpec & agent-skills

The two lighter alternatives to Spec Kit - a lightweight framework and a drop-in skill - and how each differs from the heavyweight.

Chapter 0 · Sprint Zero
Chapter 1 · The ratchet & the practice loop
2.1 · The SDD mindset & the trio
2.2 · Spec Kit, end to end
2.3 · Spec Kit in practice
2.4 · OpenSpec & agent-skills
2.5 · Choosing & adopting

Spec Kit is thorough but heavy. This lesson covers the two lighter ways to get the same discipline - spec-driven development, where you write down what you want before the agent writes code. One is a small framework; one is a skill you drop into an agent you already run.

OpenSpec: the lightweight framework

OpenSpec (from Fission AI) is a lightweight spec-driven framework. Its distinctive idea is the unit of work. Spec Kit works in whole features; OpenSpec works in the change - one bounded, reviewable delta (a single "here is what I want to add or alter"). Each change flows through a small three-step state machine:

propose  ->  apply  ->  archive
 (draft)   (build)    (record it happened)

You draft the change, implement it against that draft, then archive it once it is done and the code is real.

OpenSpec's unit is the change, not the feature - a bounded delta you can review on its own. OpenSpec

OpenSpec at a glance

One folder, openspec/, holds everything: project.md (your conventions), specs/ (the current truth - what is built), changes/ (open proposals), and an archive/ for finished ones.
A change is itself a small folder: a proposal.md (what and why), a tasks.md (the steps), and spec deltas - the exact edits, each line marked ADDED, MODIFIED, or REMOVED so a reviewer sees precisely what shifts.
The flow in commands: run openspec init once, then /opsx:propose <what-you-want>, review the proposal, implement it, and openspec archive when done.
Brownfield-first: it is built for codebases that already exist, and can reverse-engineer baseline specs from your current code so you are not starting from a blank page.
Light on setup: no Python, roughly a 5-minute install versus Spec Kit's heavier setup, and it works with 20+ agents.

("Brownfield" just means an existing project you are adding to, as opposed to a fresh "greenfield" one.) Per OpenSpec's own README, that lightness is the whole pitch: the same "spec first" habit with far less ceremony.

agent-skills: the same discipline, as a skill

The agent-skills SDD skill delivers the same discipline in a different package: a drop-in skill with no separate command-line tool to install. (A skill is a bundle of instructions an agent loads on demand.) You load it into a harness like Claude Code and it runs the same gated chain, each phase paused for a human to review before the next:

SPECIFY  ->  PLAN  ->  TASKS  ->  IMPLEMENT
 (what)     (how)     (steps)     (code)

It organises the spec around six areas: objective, commands, project structure, code style, testing strategy, and boundaries (what not to touch). Its habits are the useful part: surface hidden assumptions up front, reframe a vague instruction as a testable success condition, and keep the spec alive in version control - commit it, and reference it in your pull requests. That "committed, living spec the agent reads" is the same idea as a rules file: durable, shared, and checked in rather than lost in a chat.

The three, in one line each

Spec Kit vs OpenSpec vs agent-skills

Spec Kit - a heavy, phase-gated toolkit you install as a CLI.
OpenSpec - a light, change-based framework you install as a CLI.
agent-skills - the discipline as a drop-in skill, no CLI at all.

The split is packaging and weight, not purpose. All three keep the spec as the source of truth - the code is the output that serves it, not the other way around.

Check yourself

In OpenSpec, a change flows through -

OpenSpec's unit of work is "the change" - a bounded delta that moves propose -> apply -> archive, lighter than Spec Kit's feature-level phase gates.

Compared with Spec Kit, agent-skills needs -

agent-skills is the SDD discipline packaged as a drop-in skill you load into a harness like Claude Code - there is no standalone command-line tool to install.

What all three tools keep is that the -

Spec Kit, OpenSpec, and agent-skills differ only in packaging and weight. All three treat the spec as the durable source of truth, with code generated to serve it.

Do this now (5 min)

Open the OpenSpec README and the Spec Kit README side by side. Note one concrete way OpenSpec is lighter - shorter setup time, no Python, or "the change" as a small delta instead of full phase gates. Seeing the contrast in the wild makes the trade-off stick better than a summary.

I'm your teacher - ask freely. Not sure whether OpenSpec or the agent-skills skill fits your project better? Tell me what you are working on and I'll help you pick - and that's exactly what Lesson 2.5 tackles next.

Go deeper

Primary source (read this): OpenSpec - the lightweight, change-based framework this lesson centres on.

Secondary (for contrast): GitHub Spec Kit - skim it to feel the heavy-versus-light difference.

Wisdom (test it on people): r/ChatGPTCoding - active, cross-tool debate on which spec-driven workflow is worth the weight.

← 2.3 Spec Kit in practice Course map Glossary Next: 2.5 Choosing & adopting →