Agent skill

Sdd

by WrongStack in WrongStack/WrongStack

A skill your agent uses when the user wants a written spec, acceptance criteria, or a task graph before a non-trivial implementation, or runs the WrongStack /sdd workflow.

MITAuto-check passedProduct & Project Management

Install Sdd

skills CLI
$ npx skills add WrongStack/WrongStack --skill sdd -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install WrongStack/WrongStack sdd --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/WrongStack/WrongStack.git skills-src && mkdir -p .claude/skills && cp -r skills-src/packages/core/skills/sdd .claude/skills/sdd && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
sdd
GitHub stars
370
Token cost
~1.7k tokens
SKILL.md length
785 words
Files
2
Skills in repo
38
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses when the user wants a written spec, acceptance criteria, or a task graph before a non-trivial implementation, or runs the WrongStack /sdd workflow.

  • Works in 6 steps: Every non-trivial task needs a spec… → Spec must have acceptance criteria —… → Record real dependencies between tasks,… → …
  • The user wants a written spec
  • SKILL.md covers Overview, Rules, When to use and The SDD workflow, plus 10 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Sdd is an agent skill from WrongStack/WrongStack. Use this skill when the user wants a written spec, acceptance criteria, or a task graph before a non-trivial implementation, or runs the WrongStack /sdd workflow. Triggers: user says "/sdd", "spec", "specification", "task graph", "SDD", "acceptance criteria".

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file (for example `SKILL.save.md`).

It sits in Product & Project Management, covering User stories. The repository describes itself as: An AI coding agent that reads your code, edits files, runs commands, and reasons through bugs — across a terminal REPL, a full-screen TUI, and a browser UI, while you keep your… The licence is MIT.

When your agent uses it

  • The user wants a written spec
  • Acceptance criteria
  • A task graph before a non-trivial implementation
  • Runs the WrongStack /sdd workflow

Example prompts

  • “specification”
  • “task graph”
  • “acceptance criteria”
  • “/sdd”

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. Every non-trivial task needs a spec before writing code — you'll rewrite it anyway.
  2. Spec must have acceptance criteria — without them, you can't know when it's done.
  3. Record real dependencies between tasks, and only real ones — unchained tasks are the ones that can run in parallel.
  4. Spec must be specific: "Users authenticate via OAuth2 with PKCE" not "improve auth".
  5. Skipping /sdd for urgent tasks backfires — the spec is what makes "urgent" possible.
  6. When the spec reveals a multi-file refactor, delegate to refactor-planner first.

What it can do on your machine

Read from SKILL.md and the folder at commit 57f6018. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Sdd loads about 1.7k tokens when it runs. Until then it costs about 66 tokens; SKILL.md has 785 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~66
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from WrongStack/WrongStack at commit 57f6018, republished under its MIT licence (© WrongStack). 785 words, ~1,674 tokens.

Download SKILL.mdSave it as .claude/skills/sdd/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
sdd
description
Use this skill when the user wants a written spec, acceptance criteria, or a task graph before a non-trivial implementation, or runs the WrongStack /sdd workflow. Triggers: user says "/sdd", "spec", "specification", "task graph", "SDD", "acceptance criteria".
version
2.1.0
required-capabilities
work.plan, filesystem.write

Spec-Driven Development — WrongStack

Overview

Every non-trivial change starts with a spec. The spec is the source of truth — it defines what to build, how to verify it, and what counts as done. SDD uses /sdd slash commands to create specs, generate task graphs, and track execution.

Rules

  1. Every non-trivial task needs a spec before writing code — you'll rewrite it anyway.
  2. Spec must have acceptance criteria — without them, you can't know when it's done.
  3. Record real dependencies between tasks, and only real ones — unchained tasks are the ones that can run in parallel.
  4. Spec must be specific: "Users authenticate via OAuth2 with PKCE" not "improve auth".
  5. Skipping /sdd for urgent tasks backfires — the spec is what makes "urgent" possible.
  6. When the spec reveals a multi-file refactor, delegate to refactor-planner first.

When to use

  • New feature implementation
  • Bug fix with complexity
  • Refactoring with scope
  • Any task requiring more than 1 hour

The SDD workflow

1. /sdd new [title]          → Build spec from questions
2. /sdd tasks <id>           → Generate task graph from spec
3. /sdd graph <id>           → Visualize dependencies
4. /sdd critical <id>        → Find bottlenecks
5. /sdd execute <id>         → Run tasks (or execute manually)

Task lifecycle commands

CommandWhat it does
/sdd tasksShow task list with progress bar (sorted: in_progress → pending → review → blocked → failed → completed)
/sdd nextShow next executable task + blockers
/sdd done <N>Complete a task (by number or fuzzy title match)
/sdd skip <N>Skip a task back to pending
/sdd fail <N>Mark a task as failed
/sdd review <N>Send a task to review
/sdd edit <N> <text>Edit task title (short text) or description (long text)
/sdd undoUndo last task completion
/sdd graphASCII task dependency visualization
/sdd criticalCritical path analysis + bottlenecks

Spec templates

TemplateBest for
featureNew feature development
bugfixBug fix with root cause analysis
refactorCode refactoring with goals
infraInfrastructure/tooling changes
integrationExternal service integration
cli-commandNew CLI commands/slash commands

Spec structure

A complete spec has:

  1. Overview — What problem does this solve?
  2. Requirements — [priority] description format
  3. Architecture — High-level design (if needed)
  4. API Design — Endpoints, inputs, outputs (if applicable)
  5. Acceptance Criteria — How do we know it's done?
Requirement format
[critical] Users can authenticate with OAuth2
[high] Rate limiting: 100 req/min per user  
[medium] Response time < 200ms p95
[low] Support dark mode

Task graph generation

Each requirement generates one or more tasks. Tasks have states:

pending → in_progress → review → completed
              ↓
           blocked (waiting on dependencies)
              ↓
           failed

Critical path

The critical path finds:

  • Bottleneck tasks blocking the most downstream work
  • Parallel groups that can run concurrently
  • Ready tasks that can start immediately
  • Execution order respecting all dependencies

Goal & Eternal Mode

/sdd pairs with /goal for autonomous execution:

CommandWhat it does
/goal set <text>Set an autonomous mission
/goal pausePause at end of current iteration
/goal resumeResume a paused goal
/goal journal [N]Show recent journal entries
/goal clearClear goal and stop eternal mode
/autonomy eternalRun goal loop indefinitely
/autonomy stopStop eternal mode

Eternal stage flow: decide → execute → reflect → sleep | paused | stopped Stage shown in real-time. Pause stops after current iteration completes.

Show full SKILL.md (331 more words)Show less

Anti-patterns

  • Writing code before the spec — you'll rewrite it anyway
  • Spec that's too vague — "improve auth" is not a spec, "Users authenticate via OAuth2 with PKCE" is
  • Invented dependencies — chaining independent tasks serializes work that could run in parallel
  • Spec without acceptance criteria — how do you know when it's done?
  • Skipping /sdd for urgent tasks — the spec is what makes "urgent" possible

Out of scope

  • Don't start coding before the spec exists. You'll rewrite the code anyway — the spec is what makes the rewrite possible. SDD comes first or the spec is fiction.
  • Don't accept a spec without acceptance criteria. "Done" must be a checkable state. Without criteria, the task has no formal end and the verifier has nothing to run.
  • Don't write vague requirements. "Improve auth" is not a requirement; "Users authenticate via OAuth2 with PKCE, sessions expire after 24h" is. If a requirement can't be tested, it's not a requirement.
  • Don't skip /sdd because the task is urgent. Urgency without a spec produces urgency-shaped rework. The spec is what makes "urgent" possible to ship correctly.
  • Don't start a multi-file refactor from SDD. When the spec reveals a refactor, delegate to refactor-planner for the phased plan. SDD defines the goal; refactor-planner sequences the work.
  • Don't execute the task graph yourself unless the user asks. SDD produces the plan and task graph; an executor (the leader, a subagent, or the user) picks it up.

Before returning

  • Spec has explicit acceptance criteria the verifier can run as commands
  • Every requirement is specific enough to be tested, not "improve X"
  • Real dependencies recorded; independent tasks left unchained so they can run in parallel
  • Spec template matches the work type (feature/bugfix/refactor/infra/integration/cli-command)
  • Multi-file refactors are routed to refactor-planner, not absorbed into SDD tasks
  • Critical path called out; bottlenecks named; parallel groups identified

Skills in scope

  • refactor-planner — when the spec reveals a multi-file refactor
  • bug-hunter — when a bugfix spec needs a root cause analysis section
  • multi-agent — for executing parallel task groups
  • output-standards — for standardized <nextsteps> formatting

© WrongStack, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in packages/core/skills/sdd of WrongStack/WrongStack.

  • SKILL.md
  • SKILL.save.md

Open the folder on GitHubat commit 57f6018

Compare with similar skills

Sdd next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Sdd compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Sdd this skillWrongStack/WrongStack370—~1.7kAutomated safety check: PassMIT
User Story Writerdeanpeters/Product-Manager-Skills7.2k2 repos~2.9kAutomated safety check: PassCustom licence
To Specbestofjs/bestofjs3.1k22 repos~757Automated safety check: PassMIT
Walking Skeleton Roadmap Scopingprime-radiant-inc/iterative-development181—~1.7kAutomated safety check: PassApache-2.0
Design Sprintwondelai/skills2.4k—~3.8kAutomated safety check: PassMIT
Execute Issuelbedner/aegis-stack143—~1.1kAutomated safety check: PassMIT

Similar skills

  • User Story Writer

    deanpeters/Product-Manager-Skills

    Writes user stories in Mike Cohn's format with Gherkin acceptance criteria, turning user needs into development-ready work with testable conditions.

    7.2k GitHub starsUsed in 2 repos~2.9k tokens
    Product & Project ManagementAuto-check passed
  • To Spec

    bestofjs/bestofjs

    Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.

    3.1k GitHub starsUsed in 22 repos~757 tokens
    Product & Project ManagementAuto-check passed
  • Walking Skeleton Roadmap Scoping

    prime-radiant-inc/iterative-development

    Turns extracted requirements into a roadmap by choosing a walking skeleton iteration with its first journey scenario and ordering the remaining work into follow-on iterations.

    181 GitHub stars~1.7k tokensUpdated 4 mo ago
    Product & Project ManagementAuto-check passed
  • Design Sprint

    wondelai/skills

    Run a structured 5-day process to prototype, test, and validate product ideas with real users.

    2.4k GitHub stars~3.8k tokensUpdated 28 days ago
    Product & Project ManagementAuto-check passed
  • Execute Issue

    lbedner/aegis-stack

    A skill your agent uses when handed a GitHub issue (number or URL) to execute end to end.

    143 GitHub stars~1.1k tokensUpdated today
    Product & Project ManagementAuto-check passed
  • Refactor Design Report

    penwyp/ClaudePreference

    Produce a professional, code-grounded refactor or implementation design report from identified technical problems, product gaps, review findings, architecture concerns, or frontend-backend contract…

    136 GitHub stars~1.4k tokensUpdated 4 mo ago
    Product & Project ManagementAuto-check passed

More from WrongStack/WrongStack

All 38 skills in this repo
  • Design Craft

    WrongStack/WrongStack

    Design or substantially improve user-facing interfaces with a product-specific visual direction, content hierarchy, and rendered critique.

    370 GitHub stars~2k tokensUpdated yesterday
    Auto-check passed
  • Design Critique

    WrongStack/WrongStack

    A skill your agent uses to audit an interface that already exists and say precisely why it looks generated, templated, or unfinished — a scored rubric across composition, typography, color, states…

    370 GitHub stars~3k tokensUpdated yesterday
    Auto-check passed
  • Mailbox Bridge

    WrongStack/WrongStack

    A skill your agent uses when external coding agents (Claude Code, Aider, custom scripts) need to participate in the project's shared WrongStack mailbox, or when a user asks to "expose the mailbox"…

    370 GitHub stars~3.9k tokensUpdated yesterday
    Auto-check passed
  • Multi Agent

    WrongStack/WrongStack

    A skill your agent uses whenever work can be split across multiple AI agents running in parallel, or when orchestrating leader/worker patterns in WrongStack.

    370 GitHub stars~3.6k tokensUpdated yesterday
    Auto-check passed
  • Web Platform Baseline

    WrongStack/WrongStack

    Use this skill before asserting that a CSS, HTML or accessibility capability is available, unavailable, or the right tool — it carries dated, refreshable platform facts and refuses to let stale…

    370 GitHub stars~1.6k tokensUpdated yesterday
    Auto-check passed
  • Wrongstack Mailbox

    WrongStack/WrongStack

    A skill your agent uses when the user wants to communicate with WrongStack's shared project mailbox from outside WrongStack — read messages sent by WrongStack agents, send replies, broadcast to all…

    370 GitHub stars~3.5k tokensUpdated yesterday
    Auto-check passed

Questions about Sdd

What does Sdd do?

A skill your agent uses when the user wants a written spec, acceptance criteria, or a task graph before a non-trivial implementation, or runs the WrongStack /sdd workflow. Sdd is an agent skill from WrongStack/WrongStack. Use this skill when the user wants a written spec, acceptance criteria, or a task graph before a non-trivial implementation, or runs the WrongStack /sdd workflow.

When should I use Sdd?

Sdd fits situations like: the user wants a written spec; acceptance criteria; A task graph before a non-trivial implementation; runs the WrongStack /sdd workflow.

How do I install Sdd in Claude Code?

Run `npx skills add WrongStack/WrongStack --skill sdd -a claude-code`. Or copy the skill folder (packages/core/skills/sdd in WrongStack/WrongStack) into .claude/skills/sdd in your project. Claude Code loads it when a task matches its description.

How do I install Sdd in Codex?

Run `npx skills add WrongStack/WrongStack --skill sdd -a codex`. Or copy the skill folder (packages/core/skills/sdd in WrongStack/WrongStack) into .agents/skills/sdd in your project. Codex loads it when a task matches its description.

Can I use Sdd in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add WrongStack/WrongStack --skill sdd -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/sdd, .gemini/skills/sdd, .github/skills/sdd and .opencode/skills/sdd in your project.

What does Sdd need to run?

SKILL.md names no scripts, command-line tools or credentials: Sdd is instructions for the agent only.

Does Sdd access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Sdd safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Sdd use?

Sdd is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Sdd use?

About 1.7k tokens (SKILL.md is roughly 6.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Sdd?

Skills that share tags, products or a category with Sdd: User Story Writer (deanpeters/Product-Manager-Skills, 7.2k stars), To Spec (bestofjs/bestofjs, 3.1k stars), Walking Skeleton Roadmap Scoping (prime-radiant-inc/iterative-development, 181 stars) and Design Sprint (wondelai/skills, 2.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Sdd?

WrongStack (a GitHub organization) maintains it in WrongStack/WrongStack, which has 370 GitHub stars. The repository holds 38 skills in this directory. The repository was last updated on October 7, 2026.

Source: WrongStack/WrongStack on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.