agents-standards
Standards for authoring SDD plugin agents — frontmatter, self-containment, skill references, and no-user-interaction rules.
@liorcohenInstall SkillDevelopment
Skill
/spec-writing
Templates and validation for writing product specifications.
Claude Code
$ npx -y skills add LiorCohen/sdd --skill spec-writing --agent claude-code
Codex
$ npx skills add LiorCohen/sdd --skill spec-writing -a codex -y
Cursor
$ npx skills add LiorCohen/sdd --skill spec-writing -a cursor -y
Gemini CLI
$ npx skills add LiorCohen/sdd --skill spec-writing -a gemini-cli -y
GitHub Copilot
$ npx skills add LiorCohen/sdd --skill spec-writing -a github-copilot -y
OpenCode
$ npx skills add LiorCohen/sdd --skill spec-writing -a opencode -y
Windsurf
$ npx skills add LiorCohen/sdd --skill spec-writing -a windsurf -y
SKILL.md
spec-writing.SKILL.mdname: spec-writing
description: Templates and validation for writing product specifications.
user-invocable: false
Spec Writing Skill
Templates
Use templates below as starting points.
Input
Schema: [`schemas/input.schema.json`](./schemas/input.schema.json)
Accepts spec type, change type, title, domain, and optional issue reference.
Output
Schema: [`schemas/output.schema.json`](./schemas/output.schema.json)
Returns complete SPEC.md markdown and validation results for required fields, sections, and format.
Spec Types: Product vs Tech
**Product Specs** (external input):
- Focus on WHAT and WHY
- Typically authored by product managers or stakeholders
- Archived as-is when imported via external spec workflow
- `spec_type: product`
**Tech Specs** (generated SPEC.md files):
- Focus on HOW
- Generated from product specs + solicitation
- Full implementation details
- `spec_type: tech`
Spec Lifecycle
**Git is the state machine:**
- In PR = draft (implicit, no status field needed)
- Merged to main = active
- Explicit statuses only for: `active`, `deprecated`, `superseded`, `archived`
Spec Locations
| Type | Location | |------|----------| | Change specs | `changes/YYYY/MM/DD/<change-name>/SPEC.md` | | Implementation plans | `changes/YYYY/MM/DD/<change-name>/PLAN.md` | | Domain definitions | `specs/domain/definitions/<definition-name>.md` | | API contracts | `specs/architecture/api-contracts.md` |
**Date-based organization:**
- Changes are organized by creation date (YYYY/MM/DD)
- This provides chronological traceability
- Plans live alongside their specs in the same directory
Acceptance Criteria Format
Always use Given/When/Then:
- [ ] **AC1:** Given [precondition], when [action], then [expected result]
Resource Files
For detailed guidance, read these on-demand:
- [feature-spec-template.md](resources/feature-spec-template.md) — Complete feature spec template
- [epic-spec-template.md](resources/epic-spec-template.md) — Epic structure with child changes
- [other-templates.md](resources/other-templates.md) — Domain definition + product spec templates
- [frontmatter-validation.md](resources/frontmatter-validation.md) — Frontmatter fields + validation rules
Read more
name: spec-writing description: Templates and validation for writing product specifications. user-invocable: false
Spec Writing Skill
Templates
Use templates below as starting points.
Input
Schema: [`schemas/input.schema.json`](./schemas/input.schema.json)
Accepts spec type, change type, title, domain, and optional issue reference.
Output
Schema: [`schemas/output.schema.json`](./schemas/output.schema.json)
Returns complete SPEC.md markdown and validation results for required fields, sections, and format.
Spec Types: Product vs Tech
**Product Specs** (external input):
- Focus on WHAT and WHY
- Typically authored by product managers or stakeholders
- Archived as-is when imported via external spec workflow
- `spec_type: product`
**Tech Specs** (generated SPEC.md files):
- Focus on HOW
- Generated from product specs + solicitation
- Full implementation details
- `spec_type: tech`
Spec Lifecycle
**Git is the state machine:**
- In PR = draft (implicit, no status field needed)
- Merged to main = active
- Explicit statuses only for: `active`, `deprecated`, `superseded`, `archived`
Spec Locations
| Type | Location | |------|----------| | Change specs | `changes/YYYY/MM/DD/<change-name>/SPEC.md` | | Implementation plans | `changes/YYYY/MM/DD/<change-name>/PLAN.md` | | Domain definitions | `specs/domain/definitions/<definition-name>.md` | | API contracts | `specs/architecture/api-contracts.md` |
**Date-based organization:**
- Changes are organized by creation date (YYYY/MM/DD)
- This provides chronological traceability
- Plans live alongside their specs in the same directory
Acceptance Criteria Format
Always use Given/When/Then:
- [ ] **AC1:** Given [precondition], when [action], then [expected result]
Resource Files
For detailed guidance, read these on-demand:
- [feature-spec-template.md](resources/feature-spec-template.md) — Complete feature spec template
- [epic-spec-template.md](resources/epic-spec-template.md) — Epic structure with child changes
- [other-templates.md](resources/other-templates.md) — Domain definition + product spec templates
- [frontmatter-validation.md](resources/frontmatter-validation.md) — Frontmatter fields + validation rules
Stats
43
Stars
4
Forks
Quiet
Maintenance
TypeScript
Language
Last commit
Created
Ships withsdd
Structure for AI-assisted development AI coding assistants are powerful but chaotic. You prompt, you get code, but then what?
4359 skills7 agents
Stars on GitHub
Momentum
- stars in total
- 43
Other skills on sdd.
@liorcohenInstall Skillcommands-standards
Standards for authoring SDD plugin commands — frontmatter, user interaction, skill/agent invocation, CLI integration, and output…
@liorcohenInstall Skillcommit
Create a commit following repository guidelines with proper versioning and changelog updates.
@liorcohenInstall Skillcritic
Two-step self-review at every task lifecycle phase. Step 1 (this skill) runs in-context to gather session signals — files read vs…
@liorcohenInstall Skilld2
D2 diagramming language reference for architecture diagrams, sequence diagrams, grid layouts, SQL tables, and class diagrams.…
@liorcohenInstall Skilldocs-standards
Writes and maintains user-facing documentation for the SDD plugin. Proactively detects when docs are out of sync with plugin…
@liorcohenInstall SkillMore skills from other plugins.
Auto-invoked
brainstorming
You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or…
@obraInstall Skillask-matt
Ask which skill or flow fits your situation. A router over the skills in this repo.
@mattpocockInstall SkillAuto-invoked
Questions about spec-writing.
- Which coding agents can use spec-writing?
- spec-writing installs in Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and Windsurf with the skills CLI, using each agent's flag shown on this page. Flowy's auto-invocation, which fires a skill when your prompt matches, runs in Claude Code only.