sdd

Spec-Driven Development toolkit for AI agents.

Install battle-tested SDD skills into Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Antigravity — in seconds.

npx @ghcordeiro/sdd

What is this?

sdd installs a curated set of AI agent skills for Spec-Driven Development — spec-driven planning, architecture documentation, ADR creation, C4 diagrams, code quality review, RFC writing, and more.

All skills are installed at once, as a single toolkit. No picking and choosing — just run, select your agent, and get to work.

Each skill is a self-contained SKILL.md file that gives your AI agent deep, specialized knowledge. Plain Markdown. No cloud dependency. No lock-in.

Quick Start

npx @ghcordeiro/sdd

The interactive CLI walks you through three steps:

──────────────────────────────────────────
 ◆ SDD
   Spec-Driven Development toolkit for AI agents
──────────────────────────────────────────

  step 1 of 3 · Select agents
  ━━━━━━━━━━━━━──────────────────────────

  Which AI agent(s) do you use?

  › ○  Claude Code
    ○  Cursor
    ○  GitHub Copilot
    ○  Gemini CLI
    ○  Antigravity

  ↑↓ navigate  ·  space toggle  ·  a select all  ·  enter confirm

  step 2 of 3 · Install scope
  ━━━━━━━━━━━━━━━━━━━━━━━━━━─────────────

  Where should spec-driven be installed?

  › ◉  Global    available across all your projects
    ○  Local     this project only

  step 3 of 3 · Confirm
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Ready to install spec-driven

  Agent  Gemini CLI
  Scope  Global
         ~/.gemini/skills

  › Enter to install     c to cancel

  ✓ spec-driven installed
  → ~/.gemini/skills

Non-interactive (scripts & CI)

npx @ghcordeiro/sdd install \
  --agent claude-code \
  --skills spec-driven \
  --global

| Flag | Alias | Description | |---|---|---| | --agent <id> | -a | Target agent (see supported agents below) | | --skills <ids> | -s | Comma-separated skill IDs (e.g. spec-driven) | | --global | | Install to home directory ~/ (default) | | --local | | Install to current project directory ./ |

You can always inspect the full CLI help with:

npx @ghcordeiro/sdd --help

Supported Agents

| Agent | ID | Global install path | |---|---|---| | Claude Code | claude-code | ~/.claude/skills/ | | Cursor | cursor | ~/.cursor/rules/ | | GitHub Copilot | github-copilot | ~/.github-copilot/skills/ | | Gemini CLI | gemini-cli | ~/.gemini/skills/ | | Antigravity | antigravity | ~/.antigravity/skills/ |

Skills Included

🏗️ Planning & Architecture

| Skill | Description | |---|---| | spec-driven | Full project & feature planning with 4 adaptive phases: Specify → Plan → Tasks → Implement. Orchestrates all other skills. | | c4-architect | Generates C4 architecture diagrams (Context, Container, Component, Sequence) from source code using PlantUML. | | frontend-component-architect | Evaluates React/Angular component boundaries, API design quality, state ownership, and reuse opportunities. | | technical-design-doc-creator | Creates comprehensive Technical Design Documents (TDDs) for implementation planning. |

📋 Decision & Documentation

| Skill | Description | |---|---| | create-adr | Creates immutable Architecture Decision Records (ADRs) in MADR, Nygard, or Y-Statement format. | | create-rfc | Creates structured Request for Comments (RFCs) to drive stakeholder alignment before committing to a direction. |

🔍 Code Quality

| Skill | Description | |---|---| | code-quality-guardian | Reviews code for correctness, security, maintainability, and architecture fit — findings triaged as Critical / Warning / Suggestion. | | duplication-hunter | Detects exact and semantic code duplication and recommends low-risk shared abstractions with migration steps. | | best-practices | Audits web projects for security misconfigurations, deprecated APIs, and modern code quality standards. |

🌐 Web & Frontend

| Skill | Description | |---|---| | seo | Optimizes pages for search visibility — meta tags, structured data (JSON-LD), sitemaps, and crawlability. | | accessibility | Audits and improves web accessibility following WCAG 2.1 AA guidelines. | | chrome-devtools | Browser debugging, performance profiling, and automation via Chrome DevTools. |

⚙️ Tooling & Automation

| Skill | Description | |---|---| | gh-fix-ci | Diagnoses and fixes failing GitHub Actions CI checks by inspecting logs and drafting targeted fixes. | | cursor-subagent-creator | Creates Cursor-specific AI subagents with isolated context for complex multi-step workflows. | | skill-architect | Expert guide for designing and building new AI agent skills from scratch. |

Repository Structure

ai-skills/
├── packages/
│   ├── cli/                  # @ghcordeiro/sdd — CLI publicado no npm
│   │   ├── src/              # TypeScript source (Ink + Commander)
│   │   └── build.mjs         # esbuild bundler script
│   └── skills-catalog/       # one directory per skill
│       ├── spec-driven/
│       ├── create-adr/
│       └── ...
├── libs/
│   └── core/                 # shared logic (catalog, installer, agent definitions)
├── .github/workflows/
│   ├── ci.yml                # type-check on every push to main
│   └── publish.yml           # build + publish on version tag
├── package.json              # npm workspaces root
└── nx.json

Contributing

Adding a new skill

1. Create a new directory under packages/skills-catalog/<skill-name>/
2. Add a SKILL.md with YAML frontmatter (name, description, license)
3. Open a pull request — the skill is automatically included in the next release

Publishing a new version

# Preview release result locally (optional)
npm run release:dry-run

Releases are fully automated with semantic-release on every push to main. It automatically:

• analyzes Conventional Commits (feat, fix, BREAKING CHANGE)
• calculates the next version
• updates packages/cli/package.json + package-lock.json
• creates CHANGELOG.md
• creates git tag + GitHub release
• publishes @ghcordeiro/sdd to npm with provenance

Examples:

• fix: ... → patch release
• feat: ... → minor release
• feat!: ... or BREAKING CHANGE: → major release

Troubleshooting release

• npm ci fails with lockfile mismatch:
  • run npm install locally to sync package-lock.json
  • commit package-lock.json before tagging
• provenance/repository mismatch (E422):
  • ensure packages/cli/package.json repository.url points to the same GitHub repo used by Actions
• publish workflow not triggered:
  • ensure commit was pushed to main
  • ensure commit follows Conventional Commits so semantic-release can determine a version bump

Inspiration & Credits

This project's spec-driven skill is inspired by prior work from the community and published references on Spec-Driven Development.

Original work

• tlc-spec-driven by Felipe Rodrigues — Tech Lead's Club
• Source: tech-leads-club/agent-skills
• License: CC-BY-4.0

SDD references

• Martin Fowler — Spec-Driven Development: 3 Tools
• DS Academy — Spec-Driven Development series (parts 1-5)
• Microsoft Learn — Spec-Driven Development with GitHub Spec Kit

Toolkit skill provenance

| Skill | Credits | GitHub source | GitHub local | License | |---|---|---|---|---| | accessibility | External (web-quality-skills), adapted locally | web-accessibility upstream | sdd/accessibility | MIT | | best-practices | External (web-quality-skills), adapted locally | web-best-practices upstream | sdd/best-practices | MIT | | c4-architect | Local author (ghcordeiro) | — | sdd/c4-architect | CC-BY-4.0 | | chrome-devtools | External (upstream match), adapted locally | chrome-devtools upstream | sdd/chrome-devtools | MIT | | code-quality-guardian | Credit undeclared in metadata; maintained locally | — | sdd/code-quality-guardian | MIT | | create-adr | External (Tech Leads Club), adapted locally | create-adr upstream | sdd/create-adr | CC-BY-4.0 | | create-rfc | External (Tech Leads Club), adapted locally | create-rfc upstream | sdd/create-rfc | CC-BY-4.0 | | cursor-subagent-creator | External (Tech Leads Club), adapted locally | cursor-subagent-creator upstream | sdd/cursor-subagent-creator | CC-BY-4.0 | | duplication-hunter | Local author (ghcordeiro) | — | sdd/duplication-hunter | CC-BY-4.0 | | frontend-component-architect | Local author (ghcordeiro) | — | sdd/frontend-component-architect | CC-BY-4.0 | | gh-fix-ci | External (Tech Leads Club), adapted locally | gh-fix-ci upstream | sdd/gh-fix-ci | Apache-2.0 | | seo | External (web-quality-skills), adapted locally | seo upstream | sdd/seo | MIT | | skill-architect | External (Felipe Rodrigues / Tech Leads Club), adapted locally | skill-architect upstream | sdd/skill-architect | CC-BY-4.0 | | technical-design-doc-creator | External (Tech Leads Club), adapted locally | create-technical-design-doc upstream | sdd/technical-design-doc-creator | CC-BY-4.0 |

License

MIT — see LICENSE.

Individual skills may carry their own licenses — check each skill's directory for details.