prd-to-spec
Transform a PRD into a technical SPEC document — architecture, API design, data model, error handling, and implementation contracts. Triggers on: prd-to-spec, prd to spec, prd转spec, 需求转设计, 需求转规格, generate spec from prd, design from prd, 技术方案, 设计方案.
- Installs
- 504
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/smallnest/goal-workflow --skill prd-to-spec- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads prd-to-spec automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
prd-to-spec — PRD to Technical Specification
Transform a Product Requirements Document (PRD) into a detailed technical SPEC that an engineer or AI agent can implement against. The PRD says what to build; the SPEC says how to build it.
When to Use
- A
/prdhas been generated and you need to bridge the gap to implementation - You want architecture decisions documented before coding starts
- Multiple developers/agents will implement the feature and need a shared contract
- You need to validate technical feasibility before committing to a PRD
- You want to catch design issues early — before code is written
The Job
- Locate PRD — find or receive the PRD document
- Analyze context (optional) — if a codebase exists, scan it to understand current architecture, patterns, and constraints
- Ask clarifying questions — resolve technical ambiguities (max 3-5 questions)
- Generate SPEC — produce a structured technical specification
- Review — present to user for feedback and iteration
- Save — write final SPEC to agreed location
Step 1: Locate PRD
Find the input PRD in one of these ways:
Provide the PRD to convert:
A. File path (e.g., tasks/prd-priority-system.md)
B. GitHub Issue URL
C. Paste PRD content directly
D. Auto-detect: scan tasks/ directory for recent PRDs
If auto-detecting, list available PRDs and let the user choose:
Found PRDs in tasks/:
1. tasks/prd-priority-system.md (2024-03-15)
2. tasks/prd-user-auth.md (2024-03-10)
Which PRD should I convert? [1/2]
Step 2: Analyze Context (Optional)
Skip this step if no codebase exists yet (greenfield project). In that case, the SPEC will propose architecture from scratch based on the PRD requirements and clarifying questions.
If a codebase exists, scan it to understand:
- Existing architecture — how the current system is structured
- Tech stack — languages, frameworks, libraries already in use
- Patterns — naming conventions, file organization, error handling approach
- Database — current schema, migration tool, ORM
- API style — REST/GraphQL/gRPC, authentication method, response format
- Testing — test framework, coverage patterns, test utilities
This ensures the SPEC aligns with the existing system rather than proposing incompatible solutions.
Step 3: Clarifying Questions
Ask only when the PRD leaves technical decisions ambiguous. Focus on:
- Architecture choices — where does this feature live? New service or extend existing?
- Data storage — new table? Extend existing? Cache strategy?
- API design — new endpoints? Extend existing? Breaking changes?
- Dependencies — any new libraries needed? Version constraints?
- Performance — expected load? Latency requirements? Batch size limits?
Format:
Technical questions before I generate the SPEC:
1. Where should the priority logic live?
A. Extend existing TaskService
B. New PriorityService
C. Inline in controller
D. Let me decide based on the codebase
2. Database migration approach?
A. Add column to existing tasks table
B. New priority table with FK
C. JSON field on tasks
D. Let me decide based on current schema
3. API versioning concern?
A. Add to existing v1 endpoints
B. New v2 endpoints
C. No versioning needed
If user selects "let me decide" options, make the best choice based on codebase analysis and document the rationale in the SPEC.
Step 4: SPEC Document Structure
# SPEC: [Feature Name]
> Technical specification derived from: [PRD filename/link]
> Generated: [date] | Target branch: [branch] | Commit: [short-hash]
## 1. Summary
### 1.1 What This SPEC Covers
[One paragraph: what feature this specifies and the scope of implementation]
### 1.2 PRD Reference
- Source: [path or URL to PRD]
- User Stories covered: [US-001, US-002, ...]
- Functional Requirements covered: [FR-1, FR-2, ...]
### 1.3 Design Decisions Summary
| Decision | Choice | Rationale |
|----------|--------|-----------|
| ... | ... | ... |
---
## 2. Architecture
### 2.1 System Context
[Where this feature fits in the overall system — diagram or description]
### 2.2 Component Design
[New components/modules introduced, their responsibilities, and boundaries]
### 2.3 Module Interactions
[How new components interact with existing ones — sequence or data flow]
### 2.4 File Structure
[New files to create and existing files to modify]
src/ ├── services/ │ └── priority.service.ts [NEW] ├── controllers/ │ └── task.controller.ts [MODIFY: add priority endpoints] ├── models/ │ └── priority.model.ts [NEW] └── migrations/ └── 20240315_add_priority.ts [NEW]
---
## 3. Data Model
### 3.1 Schema Changes
[New tables, columns, indexes — with SQL or ORM notation]
### 3.2 Entity Definitions
[TypeScript interfaces / Go structs / Python dataclasses for new entities]
### 3.3 Relationships
[How new entities relate to existing ones — FK, embedded, reference]
### 3.4 Migration Plan
[Migration steps, backward compatibility, rollback strategy]
---
## 4. API Design
### 4.1 Endpoints
| Method | Path | Description | Auth | Request | Response |
|--------|------|-------------|------|---------|----------|
| ... | ... | ... | ... | ... | ... |
### 4.2 Request/Response Schemas
[Detailed shapes with field types, validation rules, and examples]
### 4.3 Error Responses
[Error codes, messages, and HTTP status codes for each failure mode]
### 4.4 Breaking Changes
[Any backward-incompatible changes and migration path for consumers]
---
## 5. Business Logic
### 5.1 Core Algorithms
[Step-by-step logic for key operations — pseudocode or structured description]
### 5.2 Validation Rules
[Input validation, business rule validation, with specific constraints]
### 5.3 State Machine
[If applicable: states, transitions, guards, and side effects]
### 5.4 Edge Cases
[Known edge cases and how they should be handled]
---
## 6. Error Handling
### 6.1 Error Taxonomy
| Error Code | HTTP Status | Condition | User Message |
|------------|-------------|-----------|--------------|
| ... | ... | ... | ... |
### 6.2 Retry Strategy
[Which operations are retryable, backoff policy, max attempts]
### 6.3 Failure Modes
[What happens when dependencies fail — graceful degradation plan]
---
## 7. Security
### 7.1 Authentication & Authorization
[Who can access what, permission model, role checks]
### 7.2 Input Validation
[Sanitization rules, injection prevention, size limits]
### 7.3 Data Protection
[Sensitive fields, encryption at rest/transit, audit logging]
---
## 8. Performance
### 8.1 Expected Load
[Estimated QPS, data volume, growth projection]
### 8.2 Optimization Strategy
[Caching, pagination, lazy loading, batch processing]
### 8.3 Database Considerations
[Index strategy, query patterns, N+1 prevention]
---
## 9. Testing Strategy
### 9.1 Unit Tests
[What to test, test boundaries, mock strategy]
### 9.2 Integration Tests
[API tests, database tests, service interaction tests]
### 9.3 Edge Case Tests
[Specific scenarios to cover based on Section 5.4]
### 9.4 Acceptance Criteria Mapping
| US/FR | Test | Type | Description |
|-------|------|------|-------------|
| US-001 | ... | unit | ... |
| FR-2 | ... | integration | ... |
---
## 10. Implementation Plan
### 10.1 Phases
[Order of implementation — what to build first, dependencies between steps]
### 10.2 Issue Mapping
[Map SPEC sections to PRD Issues for implementation tracking]
| Issue | SPEC Sections | Priority | Depends On |
|-------|--------------|----------|------------|
| #1 | 3.1, 3.4 | high | — |
| #2 | 4.1, 4.2, 5.1 | high | #1 |
| ... | ... | ... | ... |
### 10.3 Incremental Delivery
[How to ship incrementally — feature flags, dark launches, gradual rollout]
---
## 11. Open Questions & Risks
### 11.1 Unresolved Questions
- [Questions that need product/engineering input before implementation]
### 11.2 Technical Risks
| Risk | Impact | Mitigation |
|------|--------|-----------|
| ... | ... | ... |
### 11.3 Assumptions
- [Technical assumptions made during SPEC creation — validate before implementing]
Step 5: Review & Iteration
After generating the SPEC, present it and ask:
SPEC generated from PRD. Please review:
- Are the architecture choices appropriate?
- Are there missing edge cases or error scenarios?
- Is the API design consistent with existing patterns?
- Should any section have more/less detail?
Reply OK to save, or provide feedback for iteration.
Step 6: Save
Ask user for save location:
Where should I save the SPEC?
A. tasks/spec-[feature-name].md (alongside PRD, recommended)
B. docs/spec-[feature-name].md
C. Custom path: [specify]
Mapping Strategy: PRD → SPEC
How PRD elements translate to SPEC sections:
| PRD Section | SPEC Section(s) | Transformation |
|---|---|---|
| User Stories | 5. Business Logic, 9.4 Acceptance Mapping | Stories → algorithms + test cases |
| Functional Requirements | 4. API Design, 5. Business Logic | FRs → endpoints + logic |
| Acceptance Criteria | 9. Testing Strategy | Criteria → specific test scenarios |
| Non-Goals | 11.1 Open Questions | Clarify what's explicitly excluded |
| Technical Considerations | 2. Architecture, 8. Performance | Constraints → design decisions |
| Success Metrics | 8.1 Expected Load, 10.3 Delivery | Metrics → monitoring + rollout plan |
Quality Criteria
A good SPEC should pass these checks:
- Every PRD User Story has corresponding SPEC sections
- Every Functional Requirement maps to an API endpoint or business logic rule
- Every Acceptance Criterion maps to at least one test case
- Architecture choices are justified with rationale
- API schemas are specific enough to generate client code
- Error handling covers all identified failure modes
- Implementation order respects dependencies
- No "TBD" or "TODO" items — resolve or move to Open Questions
Edge Cases & Fallback
| Scenario | Handling |
|---|---|
| PRD is vague or incomplete | Generate SPEC with best-effort choices, mark assumptions in Section 11.3 |
| PRD conflicts with existing code | Flag conflicts explicitly, propose resolution in Section 11.1 |
| Feature is too large for one SPEC | Split into multiple SPECs (one per service boundary), link them |
| No existing codebase (greenfield) | Skip Step 2, propose architecture from scratch based on PRD + clarifying questions |
| PRD has no User Stories (just bullet points) | Infer structure, map bullets to SPEC sections, note in Summary |
| User wants SPEC without reading codebase | Skip Step 2, note that assumptions about existing code are unverified |
| Multiple PRDs need one SPEC | Merge PRD inputs, deduplicate requirements, note source for each |
Anti-Patterns to Avoid
- Don't restate the PRD. The SPEC adds technical depth, not a copy of requirements in different words.
- Don't over-specify trivial operations. CRUD with no special logic doesn't need a full algorithm section.
- Don't pick technologies without context. Always check what the project already uses before suggesting new tools.
- Don't design in isolation. The SPEC must fit the existing system — same patterns, same conventions, same style.
- Don't leave decisions implicit. If you made a choice (e.g., "add column to existing table"), state it and say why.
- Don't write implementation code. The SPEC describes contracts and behavior, not code. Pseudocode is acceptable for complex algorithms.
Relationship to Other Skills
/prd → /prd-to-spec → /goal → /review-it → /ship-it
│ │ │
│ Requirements │ Technical │ Implementation
│ (what) │ (how) │ (code)
- /prd produces the PRD (input to this skill)
- /prd-to-spec produces the SPEC (this skill)
- /goal implements Issues with SPEC as the technical reference
- /code-to-spec reverse-engineers SPEC from existing code (complementary — forward vs. reverse)
FAQ
What does the prd-to-spec skill do?
Transform a PRD into a technical SPEC document — architecture, API design, data model, error handling, and implementation contracts. Triggers on: prd-to-spec, prd to spec, prd转spec, 需求转设计, 需求转规格, generate spec from prd, design from prd, 技术方案, 设计方案.
How do I install prd-to-spec?
Run npx skills add https://github.com/smallnest/goal-workflow --skill prd-to-spec in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/prd-to-spec/ (personal) or .claude/skills/prd-to-spec/ (project).
Which AI agents can use prd-to-spec?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is prd-to-spec safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains prd-to-spec?
It is published by smallnest in smallnest/goal-workflow. It has 504 recorded installs.
More from smallnest/goal-workflow
smell
smallnest/goal-workflow
Detect software architecture bad smells, algorithmic complexity hotspots, and anti-patterns in a codebase. Produces a detailed markdown report identifying violations of architectural principles, design patterns, code quality, and performance complexity. Triggers on: smell, code smell, architecture smell, find anti-patterns, detect bad smells, complexity analysis, 代码坏味道, 架构坏味道, 反模式, 找出坏味道, 复杂度分析.
prd
smallnest/goal-workflow
Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. After PRD is confirmed, use /prd-to-spec (optional) for technical design, then /to-issues to create implementable tickets. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out, 写PRD, 需求文档, 需求分析, 规格说明.
humanize-it
smallnest/goal-workflow
对指定文档进行去 AI 味的改写。自动选择最合适的人性化策略（humanizer-zh / humanize-chinese / technical-writing）， 迭代改写直到效果达标或迭代 42 次为止。适用于中文文本的去 AI 化处理，包括通用文章、技术文档、学术论文等。 Use when user says: "humanize this", "去AI味", "降AIGC", "人性化改写", "改成人话", "去除AI痕迹", "humanize document", "make text human-like", "去机器味", "降低AI率", "过AIGC检测"
insight-diagram
smallnest/goal-workflow
为任意项目生成 UML 图、架构图和流程图。分析代码库后让用户选择要生成的图表类型，使用 architecture-diagram skill 渲染为 HTML+SVG，保存到 docs/ 目录。适用于任何软件项目的文档可视化。
refactor
smallnest/goal-workflow
Expert code refactoring based on Martin Fowler's catalog — improve maintainability without changing behavior. Covers code smells, composing methods, moving features, organizing data, simplifying conditionals, method calls, and generalization. Triggers on: refactor, 重构, clean up, improve code, code smell, extract method, rename, simplify.
modern-go
smallnest/goal-workflow
Modernize Go code by applying version-appropriate idioms and APIs (gofix-style transformations). Scans go.mod for the Go version, then transforms Go source files to use modern patterns—from Go 1.0 through 1.26+. Use when the user says "现代化","现代Go语言", "地道的", "idiomatic", "modernize", "modern-go", "update Go code", "gofix", or wants to upgrade Go idioms.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.