ai-agent-sdd
- Repo stars 0
- Author updated Live
- Author repo skills-registry
- Domain
- Design
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: ai-agent-sdd
description: Write a professional Software Design Document (SDD) for an AI agent or AI-powered product before…
category: design
runtime: no special runtime
---
# ai-agent-sdd output preview
## PART A: Task fit
- Use case: Write a professional Software Design Document (SDD) for an AI agent or AI-powered product before writing code. Forces the team / vibe-coding agent to clarify problem, users, success metrics, agent workflow, LLM strategy, evaluation framework, failure modes, and acceptance criteria — so implementation is bounded, testable, and shippable. Use when starting a new AI agent project, before vibe-coding a prototype, when an existing AI feature is over-running scope, or when handing off an AI product to a new owner / external developer. Two depth levels: MVP (12 sections, ~30-min fill) and Full (23 sections, ~2-hour fill). Use when this capability is needed..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “When to Use / When NOT to Use / Non-Negotiable Principles” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Write a professional Software Design Document (SDD) for an AI agent or AI-powered product before writing code. Forces the team / vibe-coding agent to clarify problem, users, success metrics, agent workflow, LLM strategy, evaluation framework, failure modes, and acceptance criteria — so implementation is bounded, testable, and shippable. Use when starting a new AI agent project, before vibe-coding a prototype, when an existing AI feature is over-running scope, or when handing off an AI product to a new owner / external developer. Two depth levels: MVP (12 sections, ~30-min fill) and Full (23 sections, ~2-hour fill). Use when this capability is needed.”.
- **02** When the source has headings, the agent prioritizes “When to Use / When NOT to Use / Non-Negotiable Principles” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “When to Use / When NOT to Use / Non-Negotiable Principles”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: ai-agent-sdd
description: Write a professional Software Design Document (SDD) for an AI agent or AI-powered product before…
category: design
source: tomevault-io/skills-registry
---
# ai-agent-sdd
## When to use
- Write a professional Software Design Document (SDD) for an AI agent or AI-powered product before writing code. Forces…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “When to Use / When NOT to Use / Non-Negotiable Principles” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "ai-agent-sdd" {
input -> user goal + target files + boundaries + acceptance criteria
context -> When to Use / When NOT to Use / Non-Negotiable Principles
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} AI Agent SDD — Software Design Document for AI Agents
You guide product teams to write a professional SDD before writing AI agent code, so vibe-coding doesn't drift into a swamp of unboundable scope, fake metrics, and untestable behavior.
A good SDD answers, in order:
- Why — what problem, for whom, measured how
- What — functional + non-functional requirements
- How — system architecture + LLM strategy + agent workflow + data + APIs + UI
- Bounds — failure modes, security, evaluation, acceptance criteria
- Sequence — phased delivery, risks, open questions
Without this, a vibe-coded AI product will (1) hallucinate its own goals mid-build, (2) be impossible to evaluate, (3) be impossible to hand off, and (4) demo well once but be unmaintainable.
When to Use
- 🚀 Starting a new AI agent / AI-powered product (greenfield)
- 🔁 An existing AI feature is mid-flight and scope is drifting
- 🤝 Handing off an AI product to a new engineer, contractor, or co-founder
- 📊 Pitching an AI product to investors / partners — need a single source of truth
- 🎯 Vibe-coding session where you want the agent to write good code, not random code
- 🧪 Defining an evaluation framework (golden set, regression checks) before shipping
When NOT to Use
- Tweaking copy / prompt one-liners (overhead too high)
- Pure infrastructure work with no LLM or agent logic (use a regular tech spec)
- Throwaway prototypes you'll abandon in <1 day (use a 5-line README)
Non-Negotiable Principles
- Problem before solution — fill sections 1-4 (Problem, Goals, Success Metrics, Personas) BEFORE writing any feature requirements
- Goals are testable — every goal has a metric and a target. "Improve UX" is not a goal
- Non-goals are explicit — what you're choosing NOT to do is as important as what you are
- No magic in agent workflow — every LLM call has model, prompt location, expected input/output documented
- Failure modes are first-class — list hallucination, infinite loops, downstream API failures BEFORE writing happy-path code
- Acceptance criteria are check-able by anyone — including a non-engineer; pass / fail must be unambiguous
- Eval framework is part of MVP — at least 10 golden inputs + expected outputs before shipping V1
Two Templates
| Template | Sections | Fill time | Use when |
|---|---|---|---|
templates/sdd-template-mvp.md |
12 | ~30 min | Small feature, single agent, pre-existing infra; or you need to start coding within hours |
templates/sdd-template-full.md |
23 | ~2 hours | New product, multi-agent system, will be handed off, will be pitched, will be open-sourced |
Default: start with MVP. Promote to Full when scope exceeds the MVP template.
Workflow — How to Run This Skill
Step 1: Decide template depth
Ask the user: "Is this a new standalone product (Full), or a feature inside an existing product (MVP)?"
Step 2: Copy the template
mkdir -p docs/sdd
cp .cursor/skills/ai-agent-sdd/templates/sdd-template-mvp.md docs/sdd/<product-slug>-sdd.md
# or sdd-template-full.md for the bigger version
Step 3: Fill section-by-section (don't skip ahead)
The template enforces a fill-order. Force the user/agent to answer each section in sequence:
- Don't allow Section 6 (Functional Requirements) to be filled until Sections 1-5 are done
- Don't allow Section 9 (Agent Workflow) to be filled until Section 8 (System Architecture) is done
- Don't allow Section 19 (Acceptance Criteria) to be filled until Sections 6-7 (FRs/NFRs) are done
This is because skipping ahead is what causes vibe-coded products to fail.
Step 4: Get sign-off before code
Once SDD is filled:
- Show it to a stakeholder (advisor, co-founder, friend with PM background) — get 1-2 critical questions
- If 50%+ of FRs are vague, send back for refinement
- If acceptance criteria can't be tested, send back
Only then start coding.
Step 5: Treat SDD as living doc
- Every PR that changes behavior must update the SDD section it affects
- At end of each phase (MVP → V1 → V2), bump version and add a changelog entry
- If SDD diverges from code by >2 sections, schedule a 30-min sync to reconcile
Section Checklist (Full template — 23 sections)
| # | Section | Required? | What it answers |
|---|---|---|---|
| 0 | Doc Metadata | ✅ | version, owner, status, last_updated, reviewers |
| 1 | TL;DR | ✅ | 3-sentence elevator pitch |
| 2 | Problem & Goals | ✅ | what's broken, what we want to achieve, what we won't try |
| 3 | Success Metrics | ✅ | primary metric + guardrails + targets |
| 4 | Personas | ✅ | primary + secondary user roles |
| 5 | User Journeys | ✅ | 2-3 narrative flows |
| 6 | Functional Requirements | ✅ | FR-1, FR-2 ... with ID, priority, acceptance |
| 7 | Non-Functional Requirements | 🟡 | latency, throughput, accuracy, cost ceiling |
| 8 | System Architecture | ✅ | high-level diagram + component list |
| 9 | LLM Strategy | ✅ (AI) | model selection, fallback chain, prompt files location |
| 10 | Agent Workflow | ✅ (AI) | state machine / DAG of steps |
| 11 | Tools / Function Calls | ✅ (AI) | list of tools agent can invoke |
| 12 | Memory Strategy | 🟡 (AI) | none / short-term / long-term |
| 13 | Human-in-the-Loop | 🟡 (AI) | where humans intervene |
| 14 | Evaluation Framework | ✅ (AI) | golden set, eval cadence, regression checks |
| 15 | Data Model | ✅ | entities, relationships, schema sketch |
| 16 | API Design | ✅ | endpoint table |
| 17 | UI / Page Structure | 🟡 | wireframe sketch, route map |
| 18 | Tech Stack & Rationale | 🟡 | why each choice |
| 19 | Deployment Topology | 🟡 | where each component runs |
| 20 | Observability | 🟡 | metrics, logs, traces, alerts |
| 21 | Cost Model | 🟡 | LLM tokens, infra, third-party APIs |
| 22 | Security & Privacy | ✅ | authn/authz, data handling, secrets |
| 23 | Failure Modes | ✅ | hallucination, infinite loop, downstream failure |
| 24 | Acceptance Criteria | ✅ | testable, verifiable |
| 25 | Phased Delivery | 🟡 | MVP → V1 → V2 |
| 26 | Open Questions & Risks | 🟡 | what's unresolved |
| 27 | Glossary | ⚪ | domain terms |
| 28 | Changelog | ⚪ | v0.1, v0.2 ... |
✅ = required · 🟡 = recommended · ⚪ = optional · (AI) = AI-specific
The MVP template (
sdd-template-mvp.md) keeps only the ✅ rows + collapses 9–14 into one "AI Behavior" section, totaling 12 sections.
Anti-Patterns to Reject
| Anti-pattern | Why it kills the SDD |
|---|---|
| "We'll add metrics later" | If you can't measure success, you can't ship |
| "The agent will figure it out" | LLM behavior must be specified, not hoped for |
| "Acceptance criteria: works as expected" | Untestable = won't be tested = silent failure in prod |
| "We'll handle errors gracefully" | List actual failure modes; "gracefully" is meaningless |
| Copying every section header but leaving content blank | A blank section is worse than no section |
| Writing SDD AFTER code is built | The doc loses its point — it's now just documentation, not design |
Pairing with Other Skills
- Before SDD:
pm-feature-specfor the broader product PRD;persona-researchfor personas - After SDD:
growth-experiment-templatefor launch experiments;daily-review-updatefor execution tracking - Implementation: run a vibe-coding session with Cursor / Claude Code, passing the SDD as context in the system prompt — "read docs/sdd/
.md, then implement section-by-section"
Output Artifact Structure
After running this skill, the workspace should contain:
docs/sdd/
└── <product-slug>-sdd.md # the filled SDD
If the product also has a PRD (from pm-feature-spec):
docs/
├── prd/<product-slug>.md # what & why (product framing)
├── sdd/<product-slug>-sdd.md # how & bounds (technical design)
└── eval/<product-slug>-golden.json # evaluation set (referenced by SDD §14)
Strategic Note
A great SDD is a forcing function for clarity. Most AI product failures are not "bad code" — they're "we didn't know what we were building." Filling out a 12-section MVP template will catch ~80% of those failures before any code is written.
Treat the SDD as the cheapest way to find out you're building the wrong thing.
Source: Celina-create/X-Studio — distributed by TomeVault.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review