Documentation.

What is specdriven?

specdriven is the home of Spec Driven Development (SDD) — a methodology where AI-generated specifications drive your project from day one. Rather than bolting AI assistance onto an existing workflow, SDD treats specs as the source of truth: they describe your stack, your architecture, and the AI skills that come bundled with them.

Concretely, it's a community library of project specs you can install into any AI coding agent — Claude Code, Cursor, GitHub Copilot, Codex, and 50+ others — with a single command.

It is open source and contributor-driven. Submissions are pull requests, reviewed by maintainers, and synced to the marketplace within an hour of merging.

What is a spec?

A spec is the production-grade scaffold for a real project: opinionated tech, architecture, file layout, and the AI workflows that fit alongside it. Each spec lives in one directory:

content/specs/<slug>/
├── SPEC.md                    REQUIRED - the spec body (markdown with YAML frontmatter)
├── specdriven-metadata.json   REQUIRED - catalog metadata (title, stack, skills, tags, ...)
├── env.example.txt            OPTIONAL - environment template
├── scripts/                   OPTIONAL - setup scripts
└── skills/                    OPTIONAL - skills bundled with this spec
    └── <skill>/
        └── SKILL.md

The SPEC.md file is what AI agents read — it follows the open Agent Skills spec. The sidecar JSON carries catalog-only metadata that the CLI ignores during install.

Where do skills fit?

Skills don't have their own catalog page on this site. They live alongside specs in one of two ways:

What you'll see after install

$ npx specdriven add nextjs-saas -a claude-code
✔ Installed spec "nextjs-saas" → .claude/specs/nextjs-saas/ (15 files)

  Paired skills — run these commands to install them:
    $ npx skills add skills-sh/community --skill code-reviewer       · skills.sh
    $ npx skills add skills-sh/community --skill api-designer        · skills.sh
    $ npx skills add skills-sh/community --skill e2e-playwright      · skills.sh
    $ npx skills add skills-sh/community --skill security-auditor    · skills.sh

The commands are catalog metadata declared on the spec. You stay in control: copy what you want, skip what you don't. Each command is independent and idempotent.

Internal vs external specs

A spec itself can also be hosted upstream rather than in the catalog repo. The install command is identical for both — the distinction only matters when you submit a new entry.

Install via CLI

The specdriven CLI is the fastest path. It downloads a spec, places it in your agent's config folder, materialises bundled skills, and writes pointer files for external skills.

Install the CLI

Run it on demand with npx, or install it globally. Requires Node 20+.

# Run without installing
npx specdriven <command>

# Or install globally and call it directly
npm install -g specdriven
specdriven <command>

Quick start

# Run interactively - the CLI prompts for slug and agent
npx specdriven add

# Install a spec into Claude Code (project-local)
npx specdriven add nextjs-saas -a claude-code

# Install for Cursor, globally
npx specdriven add nextjs-saas -a cursor -g

All commands

specdriven add [slug]        # Install a spec from the catalog (+ paired skills)
specdriven find [query]      # Search by partial name
specdriven list              # Browse alphabetically, 20 per page
specdriven init [slug]       # Scaffold a new spec from the template
specdriven remove <slug>     # Uninstall

Flags

Install manually

If you don't want the CLI, the marketplace API serves the same files as raw downloads.

Get the manifest

curl https://specdriven.sh/api/content/nextjs-saas/manifest

Returns the list of files in the spec bundle (excluding the catalog-only metadata sidecar) and their sizes.

Download a file

curl -O https://specdriven.sh/api/content/nextjs-saas/files/SPEC.md

Where to put it

Drop the file(s) into the directory your agent reads. The most common locations:

Full list of 50+ supported agents in the CLI agent registry.

Author a spec

Submissions are pull requests against specdriven-specs. CI validates the frontmatter, file types, and size limits; a maintainer reviews for usefulness and merges.

The fast path

# Scaffold from the official template
npx specdriven init my-spec

# Edit my-spec/SPEC.md, fill in specdriven-metadata.json
# Then submit a PR to specdriven-specs

SPEC.md frontmatter

---
name: nextjs-saas
description: Production SaaS template - Next.js, NextAuth, Stripe, Postgres RLS.
---

## What's included
...architecture, file structure, opinionated choices...

specdriven-metadata.json

{
  "title": "Next.js SaaS",
  "category": "webapp",
  "stack": ["Next.js 15", "TypeScript", "Drizzle", "NextAuth", "Stripe"],
  "skills": {
    "internal": [
      "drizzle-rls-reviewer"
    ],
    "external": [
      {
        "name": "code-reviewer",
        "command": "npx skills add skills-sh/community --skill code-reviewer",
        "source": "https://www.skills.sh/code-reviewer",
        "author": "skills.sh"
      }
    ]
  },
  "tags": ["saas", "auth", "billing", "nextjs"],
  "author": "your-name",
  "updated": "2026-05-21",
  "complexity": "production"
}

Adding an internal skill

Drop a skill directory under skills/ inside your spec and add the slug to skills.internal. The directory name must match the name field in SKILL.md. No catalog sidecar needed — internal skills are never published separately.

skills/drizzle-rls-reviewer/
└── SKILL.md

# skills/drizzle-rls-reviewer/SKILL.md
---
name: drizzle-rls-reviewer
description: "Reviews Drizzle queries and RLS policies for correctness and multi-tenant safety."
---
## What it does

This skill reviews every Drizzle ORM query and Postgres RLS policy change in the repo.
It catches missing tenant_id filters, unsafe policy definitions, and schema migrations
that would silently bypass row-level security in a multi-tenant context.

## Checklist

- Every query touches a table with RLS — is session context set before it runs?
- New tables include a tenant_id column with a matching RLS policy?
- Migrations don't drop or alter RLS policies without an explicit replacement?
- Drizzle schema definitions match the Postgres column types exactly?

Adding an external skill

No files needed — external skills are hosted elsewhere. Add an entry to skills.external in specdriven-metadata.json with the install command. After specdriven add, the CLI prints the command so the user can run it on demand.

"skills": {
  "external": [
    {
      "name": "e2e-playwright",
      "command": "npx skills add https://github.com/anton-abyzov/specweave --skill e2e-playwright",
      "source": "https://www.skills.sh/anton-abyzov/specweave/e2e-playwright",
      "author": "skills.sh"
    }
  ]
}

Allowed file types

Supporting files can use: .mdx .md .sh .json .yaml .yml .toml .txt .js .ts .py .xml .xsd .html .pdf .ttf .tar .gz. Per-file max 5 MB, total per spec 30 MB.

API for tool builders

Building a third-party CLI, web UI, or editor extension? Hit these endpoints directly. They're public, CDN-cacheable, and require no authentication for read traffic.

Slugs are kebab-case, max 60 chars. Files cap out at 5 MB each.

FAQ

Where did the standalone skills catalog go?

Skills are now part of specs — bundled inside the spec directory, or referenced as external pointers to wherever the canonical version lives (skills.sh, officialskills.sh, etc.). This keeps the focus on production blueprints and avoids competing with established skill catalogs.

How do I get my spec listed?

Open a PR against specdriven-specs. CI validates automatically and a maintainer reviews within 48 hours.

What can I use this for?

Anything. Everything is MIT-licensed. Commercial use, forks, derivatives — all allowed.

How are install counts tracked?

The CLI sends an anonymous POST to /api/installs after each successful install. We store no personal data, hash IPs, and deduplicate per IP per day so a single user hammering the command in a loop still counts as one install.

Why specdriven vs writing prompts inline?

Reusability and discovery. Specs make it trivial to spin up the next project with the same opinionated foundation — stack, architecture, file structure, and the AI workflows that fit.

Can I use a custom destination?

Yes. Pass --dest <path> to specdriven add, or pick Custom path… in the interactive agent prompt.

What if my agent isn't listed?

Use --dest with the agent's expected path, or open an issue with the path convention and we'll add it to the registry.