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 AI skills and 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.
Skills vs Specs
⚡ Skill
Atomic, reusable AI instruction.
A prompt, workflow, or technique that solves one concrete problem — code review, API design, security audit. Drop-in and composable.
📋 Spec
Full project blueprint.
Tech stack, architecture, and the skills that pair with it. Designed to scaffold a real, shippable project — not a toy example.
Internal vs External
Every skill and spec in the catalog is hosted one of two ways. The install command is identical for both — this distinction only matters when you submit a new entry, or when you browse the catalog and notice the External badge on a listing.
📦 Internal
Curated in the catalog repo.
The full content — SKILL.md / SPEC.md plus any supporting files — lives directly in specdriven-skills or specdriven-specs. Maintainers review the body during the PR. The CLI fetches files from the catalog API at install time.
🔗 External
Hosted upstream in your own repo.
Only the metadata sidecar lives in the catalog — a source field on specdriven-metadata.json points at your GitHub repo. The CLI fetches files directly from upstream. Submitting means adding just the metadata, no body required.
Install via CLI
The specdriven CLI is the fastest path. It downloads the skill or spec and places it into your agent's config folder, then reports an anonymous install ping for the counter.
Install the CLI
Run it on demand with npx, or install it globally to drop the prefix. 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 kind, slug, and agent
npx specdriven add
# Install a skill into Claude Code (project-local)
npx specdriven add skill code-reviewer -a claude-code
# Install a spec for Cursor, globally
npx specdriven add spec nextjs-saas -a cursor -gAll commands
specdriven add <kind> [slug] # Install from the catalog
specdriven find <kind> [query] # Search by partial name
specdriven list <kind> # Browse alphabetically, 20 per page
specdriven init <kind> [slug] # Scaffold a new one from the template
specdriven remove <kind> <slug> # UninstallFlags
| Flag | Description |
|---|---|
-a, --agent <id> | Target agent (e.g. claude-code, cursor) |
-g, --global | Install into the user-level config dir |
-d, --dest <path> | Override the destination root |
-f, --force | Overwrite if the destination already exists |
-y, --yes | Skip prompts; require all args/flags |
POST to /api/installs after each successful add. No personal data, dedup'd per IP per day server-side. Set SPECDRIVEN_API_BASE to point at a different host for local testing.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/skill/code-reviewer/manifestReturns the list of files in the skill bundle (excluding the catalog-only metadata sidecar) and their sizes.
Download a file
curl -O https://specdriven.sh/api/content/skill/code-reviewer/files/SKILL.mdWhere to put it
Drop the file(s) into the directory your agent reads. The most common locations:
| Agent | Project path | Global path |
|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| Cursor | .agents/skills/ | ~/.cursor/skills/ |
| GitHub Copilot | .agents/skills/ | ~/.copilot/skills/ |
| Codex | .agents/skills/ | ~/.codex/skills/ |
| OpenClaw | skills/ | ~/.openclaw/skills/ |
Full list of 50+ supported agents in the CLI agent registry. Replace /skills/ with /specs/ for spec installs.
Author a skill or spec
Submissions are pull requests against the source repos. 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 skill my-skill
# Edit my-skill/my-skill.mdx, add supporting files
# Then submit a PR to specdriven-skillsDirectory layout
content/skills/<slug>/
├── SKILL.md REQUIRED - agent-spec entry (name, description, body)
├── specdriven-metadata.json REQUIRED - catalog metadata (title, category, tags, ...)
├── scripts/ OPTIONAL - supporting scripts
│ └── setup.sh
└── examples/ OPTIONAL - usage examples
└── prompt.mdThe format separates two concerns: SKILL.md is the canonical file that AI agents read — it follows the open Agent Skills spec and contains the actual instructions. specdriven-metadata.json is a sidecar with catalog-only fields (title, category, tags). The CLI installs SKILL.md but skips the sidecar — agents don't need it.
SKILL.md frontmatter
---
name: api-designer
description: Generate REST and GraphQL specs with proper versioning.
---
## What it does
...100+ words of content...specdriven-metadata.json
{
"title": "API Designer",
"category": "architecture",
"tools": ["Claude", "GPT", "Gemini"],
"tags": ["api", "rest", "graphql"],
"author": "your-name",
"updated": "2026-05-08"
}SPEC.md and the metadata adds stack, skills (slugs of companion skills), and complexity (starter / production / enterprise). Full schema in SKILL_REQUIREMENTS.md and SPEC_REQUIREMENTS.md.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 skill or 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.
| Endpoint | Returns |
|---|---|
| GET /api/content/{kind}/index | Catalog index: array of { slug, title, description, category, tags, updated } |
| GET /api/content/{kind}/{slug}/manifest | File list for one entry: { entryPoint, files: [{ path, size }] } |
| GET /api/content/{kind}/{slug}/files/{...path} | Streams one file. Served as attachment with proper content-type. |
| GET /api/template/{kind}/manifest | Manifest for the canonical skill/spec template. |
| GET /api/template/{kind}/files/{...path} | Streams one template file. |
| POST /api/installs | Report an install: { kind, slug, agent, os? }. Requires User-Agent: specdriven-cli/X.Y.Z. Rate-limited per IP, dedup'd per day. |
| GET /api/installs?kind=skill&slug=... | Read install count for a slug (or batch via ?slugs=a,b,c). |
kind is skill or spec. Slugs are kebab-case, max 60 chars. Files cap out at 5 MB each.
FAQ
How do I get my skill or spec listed?
Open a PR against specdriven-skills or 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. Skills tested across many projects beat ad-hoc prompts. Specs make it trivial to spin up the next project with the same opinionated foundation. Plus the community vets quality before anything lands in the catalog.
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.