Skip to content

ghcordeiro/sdd

BranchesTags

Repository files navigation

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.

npm version CI License: MIT Node.js ≥22

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

SDD references

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.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 5

v1.2.0 Latest
Apr 1, 2026
+ 4 releases

Contributors

Languages