Prd To Appspec
- 1 installs
- 404 repo stars
- Updated August 5, 2026
- aiskillstore/marketplace
prd-to-appspec is a Claude Code skill that converts a Product Requirements Document into a structured XML app specification optimized for AI coding agents.
About
prd-to-appspec is a Claude Code skill that converts a Product Requirements Document into a structured XML app specification optimized for AI coding agents. It runs a /convert-prd workflow that extracts data models, features, implementation steps, and success criteria, turning developer-focused HOW into a declarative WHAT. A developer uses it to prepare an existing PRD so a coding agent can consume it as an app_spec.txt.
- Converts a PRD into a structured XML app specification for AI coding agents
- Transforms implementation-focused docs into declarative WHAT-to-build specs
- Runs a /convert-prd workflow: schema, features, steps, and success criteria
Prd To Appspec by the numbers
- 1 all-time installs (skills.sh)
- Ranked #1,366 of 1,879 Documentation skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
prd-to-appspec capabilities & compatibility
Free; a conversion workflow with no external service
- Capabilities
- documentation · spec generation · planning
- Use cases
- documentation · planning
- Pricing
- Free
What prd-to-appspec says it does
Transform PRDs (Product Requirements Documents) into structured XML app specifications optimized for AI coding agents.
The app_spec tells an agent WHAT to build without dictating exact implementation.
npx skills add https://github.com/aiskillstore/marketplace --skill prd-to-appspecAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 1 |
|---|---|
| repo stars | ★ 404 |
| Last updated | August 5, 2026 |
| Repository | aiskillstore/marketplace ↗ |
What it does
Convert a developer PRD into a declarative XML app spec that AI coding agents can consume.
Who is it for?
Preparing an existing PRD as a declarative spec an AI coding agent can build from
Skip if: Writing the PRD from scratch or implementing the code itself
When should I use this skill?
The user says convert PRD, generate app spec, transform PRD, or create specification from requirements
What you get
A declarative app_spec.txt XML describing WHAT to build without dictating implementation.
- app_spec.txt XML specification
By the numbers
- output has 8 XML sections
- maps 6 PRD element types to spec equivalents
Files
PRD to App Spec Converter
Transform Product Requirements Documents (PRDs) into structured XML application specifications optimized for AI coding agents.
When to Activate This Skill
- Convert a PRD to app spec format
- Generate XML specification from requirements document
- Transform technical PRD for agent consumption
- Prepare documentation for AI coding agent
- Create app_spec.txt from existing PRD
What This Skill Does
Converts developer-focused PRDs (with code snippets, TDD plans, implementation details) into declarative XML specifications that AI coding agents can consume more effectively.
Input: PRD with technical details, code examples, architecture decisions Output: Structured app_spec.txt in XML format
How to Execute
Run the `/convert-prd` workflow, which provides:
1. PRD file location (prompts if not provided) 2. Section-by-section extraction and transformation 3. Pydantic models → database schema conversion 4. Implementation code → feature descriptions 5. Epics/tasks → numbered implementation steps 6. Test assertions → success criteria 7. Final XML output with validation
Core Transformations
| PRD Has | App Spec Gets |
|---|---|
| Function implementations | Feature descriptions |
| Pydantic field validators | Data constraints in prose |
| Try/except patterns | Error handling requirements |
| Test assertions | Success criteria |
| CLI commands | API/command summaries |
| Directory structure | Technology stack context |
Output Template Structure
<project_specification>
<project_name>...</project_name>
<overview>...</overview>
<technology_stack>...</technology_stack>
<core_features>...</core_features>
<database_schema>...</database_schema>
<api_endpoints_summary>...</api_endpoints_summary>
<implementation_steps>...</implementation_steps>
<success_criteria>...</success_criteria>
</project_specification>Key Principle
- PRD: Shows HOW (implementation details)
- App Spec: Describes WHAT (requirements and expectations)
The app_spec tells an agent WHAT to build without dictating exact implementation.
Full Workflow Reference
For complete step-by-step instructions: workflows/convert-prd.md
{
"schema_version": "2.0",
"meta": {
"generated_at": "2026-01-16T13:42:17.913Z",
"slug": "aaronabuusama-prd-to-appspec",
"source_url": "https://github.com/AaronAbuUsama/alpha-arena/tree/develop/.claude/skills/prd-to-appspec",
"source_ref": "develop",
"model": "claude",
"analysis_version": "3.0.0",
"source_type": "community",
"content_hash": "67a3b2a813e9b9375356b71339289efcb81fd003bf3616fc12e311953ccfded2",
"tree_hash": "115a1de0f6e695964d41ce0f2d654da2936091233e1858669f7f1470e70b93ca"
},
"skill": {
"name": "prd-to-appspec",
"description": "Transform PRDs (Product Requirements Documents) into structured XML app specifications optimized for AI coding agents. Converts developer-focused docs with code examples into declarative agent-consumable format. USE WHEN user says \"convert PRD\", \"generate app spec\", \"transform PRD\", \"create specification from requirements\", or wants to prepare a PRD for agent consumption.",
"summary": "Transform PRDs (Product Requirements Documents) into structured XML app specifications optimized for...",
"icon": "📋",
"version": "1.0.0",
"author": "AaronAbuUsama",
"license": "MIT",
"category": "documentation",
"tags": [
"prd",
"xml",
"specification",
"ai-agents",
"documentation"
],
"supported_tools": [
"claude",
"codex",
"claude-code"
],
"risk_factors": [
"network",
"filesystem",
"external_commands"
]
},
"security_audit": {
"risk_level": "safe",
"is_blocked": false,
"safe_to_publish": true,
"summary": "Pure documentation skill containing only markdown files. All 151 static findings are false positives caused by the scanner misinterpreting Pydantic validators as crypto algorithms, markdown code fences as shell execution, and documentation links as path traversal. No executable code, scripts, network operations, or file system access capabilities.",
"risk_factor_evidence": [
{
"factor": "network",
"evidence": [
{
"file": "skill-report.json",
"line_start": 6,
"line_end": 6
},
{
"file": "SKILL-v2.md",
"line_start": 75,
"line_end": 75
},
{
"file": "SKILL-v2.md",
"line_start": 209,
"line_end": 209
}
]
},
{
"factor": "filesystem",
"evidence": [
{
"file": "skill-report.json",
"line_start": 6,
"line_end": 6
},
{
"file": "SKILL-v2.md",
"line_start": 62,
"line_end": 62
},
{
"file": "SKILL-v2.md",
"line_start": 62,
"line_end": 62
},
{
"file": "SKILL-v2.md",
"line_start": 64,
"line_end": 64
},
{
"file": "SKILL-v2.md",
"line_start": 64,
"line_end": 64
}
]
},
{
"factor": "external_commands",
"evidence": [
{
"file": "SKILL-v2.md",
"line_start": 45,
"line_end": 45
},
{
"file": "SKILL-v2.md",
"line_start": 66,
"line_end": 66
},
{
"file": "SKILL-v2.md",
"line_start": 72,
"line_end": 72
},
{
"file": "SKILL-v2.md",
"line_start": 73,
"line_end": 73
},
{
"file": "SKILL-v2.md",
"line_start": 73,
"line_end": 73
},
{
"file": "SKILL-v2.md",
"line_start": 74,
"line_end": 74
},
{
"file": "SKILL-v2.md",
"line_start": 75,
"line_end": 75
},
{
"file": "SKILL-v2.md",
"line_start": 76,
"line_end": 76
},
{
"file": "SKILL-v2.md",
"line_start": 77,
"line_end": 77
},
{
"file": "SKILL-v2.md",
"line_start": 78,
"line_end": 78
},
{
"file": "SKILL-v2.md",
"line_start": 78,
"line_end": 78
},
{
"file": "SKILL-v2.md",
"line_start": 82,
"line_end": 82
},
{
"file": "SKILL-v2.md",
"line_start": 86,
"line_end": 105
},
{
"file": "SKILL-v2.md",
"line_start": 105,
"line_end": 119
},
{
"file": "SKILL-v2.md",
"line_start": 119,
"line_end": 181
},
{
"file": "SKILL-v2.md",
"line_start": 181,
"line_end": 188
},
{
"file": "SKILL-v2.md",
"line_start": 188,
"line_end": 193
},
{
"file": "SKILL-v2.md",
"line_start": 193,
"line_end": 196
},
{
"file": "SKILL-v2.md",
"line_start": 196,
"line_end": 202
},
{
"file": "SKILL-v2.md",
"line_start": 202,
"line_end": 207
},
{
"file": "SKILL-v2.md",
"line_start": 207,
"line_end": 212
},
{
"file": "SKILL-v2.md",
"line_start": 212,
"line_end": 215
},
{
"file": "SKILL-v2.md",
"line_start": 215,
"line_end": 220
},
{
"file": "SKILL-v2.md",
"line_start": 220,
"line_end": 225
},
{
"file": "SKILL-v2.md",
"line_start": 225,
"line_end": 230
},
{
"file": "SKILL-v2.md",
"line_start": 230,
"line_end": 233
},
{
"file": "SKILL-v2.md",
"line_start": 233,
"line_end": 240
},
{
"file": "SKILL-v2.md",
"line_start": 240,
"line_end": 259
},
{
"file": "SKILL-v2.md",
"line_start": 259,
"line_end": 262
},
{
"file": "SKILL-v2.md",
"line_start": 262,
"line_end": 264
},
{
"file": "SKILL-v2.md",
"line_start": 264,
"line_end": 266
},
{
"file": "SKILL-v2.md",
"line_start": 266,
"line_end": 269
},
{
"file": "SKILL-v2.md",
"line_start": 269,
"line_end": 274
},
{
"file": "SKILL-v2.md",
"line_start": 274,
"line_end": 277
},
{
"file": "SKILL-v2.md",
"line_start": 277,
"line_end": 281
},
{
"file": "SKILL-v2.md",
"line_start": 281,
"line_end": 284
},
{
"file": "SKILL-v2.md",
"line_start": 284,
"line_end": 289
},
{
"file": "SKILL-v2.md",
"line_start": 289,
"line_end": 292
},
{
"file": "SKILL-v2.md",
"line_start": 292,
"line_end": 297
},
{
"file": "SKILL-v2.md",
"line_start": 297,
"line_end": 300
},
{
"file": "SKILL-v2.md",
"line_start": 300,
"line_end": 305
},
{
"file": "SKILL-v2.md",
"line_start": 305,
"line_end": 310
},
{
"file": "SKILL-v2.md",
"line_start": 310,
"line_end": 313
},
{
"file": "SKILL-v2.md",
"line_start": 313,
"line_end": 316
},
{
"file": "SKILL.md",
"line_start": 23,
"line_end": 23
},
{
"file": "SKILL.md",
"line_start": 27,
"line_end": 27
},
{
"file": "SKILL.md",
"line_start": 50,
"line_end": 61
},
{
"file": "SKILL.md",
"line_start": 61,
"line_end": 72
},
{
"file": "workflows/convert-prd.md",
"line_start": 8,
"line_end": 8
},
{
"file": "workflows/convert-prd.md",
"line_start": 12,
"line_end": 16
},
{
"file": "workflows/convert-prd.md",
"line_start": 16,
"line_end": 38
},
{
"file": "workflows/convert-prd.md",
"line_start": 38,
"line_end": 43
},
{
"file": "workflows/convert-prd.md",
"line_start": 43,
"line_end": 52
},
{
"file": "workflows/convert-prd.md",
"line_start": 52,
"line_end": 62
},
{
"file": "workflows/convert-prd.md",
"line_start": 62,
"line_end": 72
},
{
"file": "workflows/convert-prd.md",
"line_start": 72,
"line_end": 76
},
{
"file": "workflows/convert-prd.md",
"line_start": 76,
"line_end": 79
},
{
"file": "workflows/convert-prd.md",
"line_start": 79,
"line_end": 85
},
{
"file": "workflows/convert-prd.md",
"line_start": 85,
"line_end": 91
},
{
"file": "workflows/convert-prd.md",
"line_start": 91,
"line_end": 91
},
{
"file": "workflows/convert-prd.md",
"line_start": 91,
"line_end": 92
},
{
"file": "workflows/convert-prd.md",
"line_start": 92,
"line_end": 92
},
{
"file": "workflows/convert-prd.md",
"line_start": 92,
"line_end": 93
},
{
"file": "workflows/convert-prd.md",
"line_start": 93,
"line_end": 93
},
{
"file": "workflows/convert-prd.md",
"line_start": 93,
"line_end": 94
},
{
"file": "workflows/convert-prd.md",
"line_start": 94,
"line_end": 94
},
{
"file": "workflows/convert-prd.md",
"line_start": 94,
"line_end": 95
},
{
"file": "workflows/convert-prd.md",
"line_start": 95,
"line_end": 95
},
{
"file": "workflows/convert-prd.md",
"line_start": 95,
"line_end": 96
},
{
"file": "workflows/convert-prd.md",
"line_start": 96,
"line_end": 96
},
{
"file": "workflows/convert-prd.md",
"line_start": 96,
"line_end": 97
},
{
"file": "workflows/convert-prd.md",
"line_start": 97,
"line_end": 102
},
{
"file": "workflows/convert-prd.md",
"line_start": 102,
"line_end": 110
},
{
"file": "workflows/convert-prd.md",
"line_start": 110,
"line_end": 113
},
{
"file": "workflows/convert-prd.md",
"line_start": 113,
"line_end": 122
},
{
"file": "workflows/convert-prd.md",
"line_start": 122,
"line_end": 131
},
{
"file": "workflows/convert-prd.md",
"line_start": 131,
"line_end": 137
},
{
"file": "workflows/convert-prd.md",
"line_start": 137,
"line_end": 140
},
{
"file": "workflows/convert-prd.md",
"line_start": 140,
"line_end": 147
},
{
"file": "workflows/convert-prd.md",
"line_start": 147,
"line_end": 163
},
{
"file": "workflows/convert-prd.md",
"line_start": 163,
"line_end": 171
},
{
"file": "workflows/convert-prd.md",
"line_start": 171,
"line_end": 174
},
{
"file": "workflows/convert-prd.md",
"line_start": 174,
"line_end": 181
},
{
"file": "workflows/convert-prd.md",
"line_start": 181,
"line_end": 185
},
{
"file": "workflows/convert-prd.md",
"line_start": 185,
"line_end": 191
},
{
"file": "workflows/convert-prd.md",
"line_start": 191,
"line_end": 198
},
{
"file": "workflows/convert-prd.md",
"line_start": 198,
"line_end": 199
},
{
"file": "workflows/convert-prd.md",
"line_start": 199,
"line_end": 201
},
{
"file": "workflows/convert-prd.md",
"line_start": 201,
"line_end": 204
},
{
"file": "workflows/convert-prd.md",
"line_start": 204,
"line_end": 218
},
{
"file": "workflows/convert-prd.md",
"line_start": 218,
"line_end": 230
},
{
"file": "workflows/convert-prd.md",
"line_start": 230,
"line_end": 233
},
{
"file": "workflows/convert-prd.md",
"line_start": 233,
"line_end": 237
},
{
"file": "workflows/convert-prd.md",
"line_start": 237,
"line_end": 239
},
{
"file": "workflows/convert-prd.md",
"line_start": 239,
"line_end": 243
},
{
"file": "workflows/convert-prd.md",
"line_start": 243,
"line_end": 247
},
{
"file": "workflows/convert-prd.md",
"line_start": 247,
"line_end": 252
},
{
"file": "workflows/convert-prd.md",
"line_start": 252,
"line_end": 265
},
{
"file": "workflows/convert-prd.md",
"line_start": 265,
"line_end": 271
},
{
"file": "workflows/convert-prd.md",
"line_start": 271,
"line_end": 283
},
{
"file": "workflows/convert-prd.md",
"line_start": 283,
"line_end": 295
},
{
"file": "workflows/convert-prd.md",
"line_start": 295,
"line_end": 297
},
{
"file": "workflows/convert-prd.md",
"line_start": 297,
"line_end": 304
},
{
"file": "workflows/convert-prd.md",
"line_start": 304,
"line_end": 325
},
{
"file": "workflows/convert-prd.md",
"line_start": 325,
"line_end": 341
}
]
}
],
"critical_findings": [],
"high_findings": [],
"medium_findings": [],
"low_findings": [],
"dangerous_patterns": [],
"files_scanned": 4,
"total_lines": 926,
"audit_model": "claude",
"audited_at": "2026-01-16T13:42:17.913Z"
},
"content": {
"user_title": "Convert PRD to AI App Specification",
"value_statement": "Transform technical Product Requirements Documents into structured XML specifications optimized for AI coding agents. Converts code-heavy PRDs into declarative, agent-consumable formats that improve AI code generation quality.",
"seo_keywords": [
"prd to appspec",
"xml specification",
"ai agent requirements",
"product requirements document",
"claude code",
"ai coding",
"software specification",
"technical documentation",
"claude",
"codex"
],
"actual_capabilities": [
"Extract project name, tech stack, and overview from PRD documents",
"Transform Pydantic models into database schema definitions",
"Convert implementation code into feature descriptions",
"Generate numbered implementation steps from epics and tasks",
"Derive success criteria from test assertions"
],
"limitations": [
"Requires a well-structured PRD with technical details",
"Does not modify source code files",
"Output quality depends on input PRD completeness"
],
"use_cases": [
{
"target_user": "Technical leads",
"title": "Standardize hand-offs",
"description": "Create consistent app specifications from team PRDs for AI-assisted development"
},
{
"target_user": "AI developers",
"title": "Prepare docs for agents",
"description": "Transform existing PRDs into formats that AI coding agents can process effectively"
},
{
"target_user": "Project managers",
"title": "Generate agent specs",
"description": "Convert requirement documents into structured formats for autonomous AI development"
}
],
"prompt_templates": [
{
"title": "Basic conversion",
"scenario": "Simple PRD file",
"prompt": "Convert my PRD.md file to an app specification using the prd-to-appspec skill"
},
{
"title": "With code examples",
"scenario": "Technical PRD",
"prompt": "Transform my PRD that contains Pydantic models, test cases, and implementation code into an XML app spec"
},
{
"title": "Full transformation",
"scenario": "Complete project PRD",
"prompt": "Run the complete convert-prd workflow on my trading-bot/PRD.md file including schema extraction and success criteria derivation"
},
{
"title": "Batch processing",
"scenario": "Multiple PRDs",
"prompt": "Process all PRD files in my projects/ directory and generate corresponding app_spec.xml files for each"
}
],
"output_examples": [
{
"input": "Convert PRD.md to an app spec",
"output": [
"Project: Trading Analysis Bot",
"Tech Stack: Python 3.11+, pandas, ccxt",
"Features: Data fetching, analysis, charting, CLI",
"Schema: Candles, analyses, configurations, fetch_configs",
"Implementation Steps: 8 phases",
"Success Criteria: 9 measurable outcomes"
]
}
],
"best_practices": [
"Include code examples, Pydantic models, and test assertions in your PRD for best transformation results",
"Validate the output XML against the validation checklist before using it with AI agents",
"Group features by domain (data fetching, processing, output) to improve AI comprehension"
],
"anti_patterns": [
"Including actual code snippets in the output app spec instead of feature descriptions",
"Using vague success criteria like works well instead of measurable outcomes",
"Prescribing implementation details (specific libraries, patterns) instead of stating requirements"
],
"faq": [
{
"question": "Which AI platforms support this skill?",
"answer": "Compatible with Claude, Codex, and Claude Code. Works with any LLM-based coding agent."
},
{
"question": "What PRD formats are supported?",
"answer": "Markdown files with project name, tech stack, features, code examples, and implementation details."
},
{
"question": "Does this integrate with other tools?",
"answer": "Runs as a standalone workflow. Input PRD file path and output app_spec.txt location."
},
{
"question": "Is my data safe?",
"answer": "Processes files locally. No data is sent to external services. Runs within your workspace."
},
{
"question": "What if my PRD is incomplete?",
"answer": "The workflow guides you through extraction. Missing sections can be derived from code and directory structure."
},
{
"question": "How is this different from other spec generators?",
"answer": "Specifically designed for AI consumption. Transforms code to declarative descriptions, preserving constraints while removing implementation details."
}
]
},
"file_structure": [
{
"name": "workflows",
"type": "dir",
"path": "workflows",
"children": [
{
"name": "convert-prd.md",
"type": "file",
"path": "workflows/convert-prd.md",
"lines": 342
}
]
},
{
"name": "SKILL-v2.md",
"type": "file",
"path": "SKILL-v2.md",
"lines": 317
},
{
"name": "SKILL.md",
"type": "file",
"path": "SKILL.md",
"lines": 73
}
]
}
PRD to App Spec Converter
Transform Product Requirements Documents into structured XML application specifications optimized for AI coding agents.
When to Activate This Skill
- Convert PRD to app spec format
- Generate XML specification from requirements
- Transform technical PRD for agent consumption
- Prepare documentation for autonomous coding agent
- Create app_spec.txt from existing PRD
What Is a PRD? (Input Format)
A Product Requirements Document is a developer-focused specification containing:
Required Sections:
- Project name/title
- Technology stack (languages, frameworks, dependencies)
- Feature descriptions or user stories
- Data models (classes, schemas, types)
Common Sections:
- Implementation details (code snippets, algorithms)
- Directory structure
- Test plans or assertions
- CLI/API interface definitions
- Architecture decisions
- Epic/milestone breakdown
PRD Style: Technical, implementation-focused, shows HOW to build
Examples:
- Pydantic models with validators
- Function implementations with error handling
- TDD test cases with assertions
- CLI command definitions with typer decorators
- Database migrations or ORM schemas
See references/prd-examples.md for annotated examples.
What Is an App Spec? (Output Format)
A Project Specification is an agent-consumable requirements document:
Format: XML with semantic sections Style: Declarative, constraint-focused, describes WHAT to build
Core Philosophy: 1. No code snippets - Convert to descriptions 2. Keep constraints - "positive values", "required field", "max 100 chars" 3. Remove implementation - No "use try/except" or "call func()" 4. Preserve intent - Why this feature exists, what problem it solves
Two Appspec Archetypes:
- Product-focused (UI/UX heavy): User flows, design systems, interactions
- Example: Claude.ai clone
- System-focused (Algorithm heavy): State machines, edge cases, data flows
- Example: Alpha Arena
See references/appspec-styles.md for detailed comparison.
Core Transformation Principles
| # | Principle | Example |
|---|---|---|
| 1 | Code → Descriptions | def validate(x): assert x > 0 → "Must be positive value" |
| 2 | Models → Schema | class User(BaseModel): → <users> table with fields |
| 3 | Tests → Criteria | assert len(df) == 50 → "Returns exactly 50 records" |
| 4 | Functions → Features | async def fetch() → "Fetch data with retry logic" |
| 5 | Epics → Steps | Task list → <implementation_steps> with milestones |
| 6 | Comments → Constraints | # Must be UTC → "All timestamps in UTC format" |
| 7 | Imports → Tech Stack | from fastapi import → <framework>FastAPI</framework> |
How to Execute
Run the multi-agent workflow: workflows/convert-prd.md
Workflow Overview (5 Phases)
1. SCAN (Haiku agent)
└─ Classify project type, identify PRD sections
2. TRANSFORM (3-5 parallel Sonnet agents)
├─ Agent A: Extract metadata + tech stack
├─ Agent B: Transform data models → schema
├─ Agent C: Extract features + API surface
├─ Agent D: Convert implementation plan → steps
└─ Agent E: Derive success criteria from tests
3. VALIDATE (Parallel Haiku agents)
└─ Score each section 0-100 for quality/completeness
4. REFINE (Sonnet agent)
└─ Synthesize sections, ensure coherence, fix gaps
5. OUTPUT
└─ Write app_spec.txt with validation reportQuality Scoring (Used in Phase 3)
Each section scored 0-100:
- 0-25: Incomplete, missing critical info, has code snippets
- 26-50: Partial, lacks constraints or context
- 51-75: Good, mostly declarative, minor gaps
- 76-100: Excellent, complete, clear, agent-ready
Threshold: Sections scoring <60 trigger refinement loop.
Expected Output Structure
<project_specification>
<project_name>Name (no version)</project_name>
<version>X.Y.Z</version>
<overview>3-5 sentence summary</overview>
<technology_stack>
<language>Primary language</language>
<core_dependencies>
<dependency name="lib">Purpose</dependency>
</core_dependencies>
</technology_stack>
<prerequisites>
<existing_assets>What already exists</existing_assets>
<constraints>Limitations and rules</constraints>
</prerequisites>
<core_features>
<feature_group>
- Declarative feature descriptions
- With constraints and requirements
</feature_group>
</core_features>
<database_schema>
<table_name>
- field: type (constraint)
- related_id: foreign key (references table)
</table_name>
</database_schema>
<api_endpoints_summary>
<group>
- VERB /path/to/endpoint
Description of what it does
</group>
</api_endpoints_summary>
<implementation_steps>
<step number="1">
<title>Milestone name</title>
<deliverable>What is done</deliverable>
<tasks>
- Concrete actionable tasks
</tasks>
</step>
</implementation_steps>
<success_criteria>
<functionality>
- Measurable outcomes
</functionality>
<technical_quality>
- Code quality metrics
</technical_quality>
</success_criteria>
<directory_structure>
Annotated tree showing where code lives
</directory_structure>
</project_specification>Common Transformation Patterns
Pydantic → Schema
PRD:
class Order(BaseModel):
id: str = Field(default_factory=uuid4)
amount: float = Field(gt=0)
status: Literal["pending", "filled", "cancelled"]Appspec:
<order>
- id: string (UUID, auto-generated)
- amount: float (positive)
- status: enum ["pending", "filled", "cancelled"]
</order>Try/Except → Error Handling
PRD:
try:
result = api.fetch()
except NetworkError:
retry_with_backoff()Appspec:
<error_handling>
- Network errors: Retry with exponential backoff
- API errors: Log and return descriptive message
</error_handling>Test → Criteria
PRD:
def test_fills_on_touch():
order = place_order(entry=100)
candle = Candle(low=99, high=101)
assert order.status == "filled"Appspec:
<success_criteria>
<functionality>
- Order fills when candle touches entry price
- Fill simulation accurate for limit orders
</functionality>
</success_criteria>Validation Checklist
Before finalizing app_spec.txt:
- [ ] No code snippets remain (all converted to descriptions)
- [ ] All constraints preserved ("positive", "required", "max N")
- [ ] Clear project archetype (product vs system vs library)
- [ ] Sections match archetype (UI flows for product, edge cases for system)
- [ ] Implementation steps are actionable (not just "write tests")
- [ ] Success criteria are measurable (not vague "good UX")
- [ ] XML is well-formed (matching tags, valid structure)
- [ ] Tech stack includes all major dependencies
- [ ] Database schema shows relationships (foreign keys)
Key Anti-Patterns to Avoid
❌ Including code snippets
<bad>
Use this function:def foo(): ...
</bad>✅ Describe behavior
<good>
- Function validates input before processing
- Returns error for invalid format
</good>❌ Prescribing implementation
<bad>
Use FastAPI decorators with async/await pattern
</bad>✅ State requirements
<good>
- REST API with async request handling
- Support concurrent requests efficiently
</good>❌ Vague success criteria
<bad>
- Application works well
- Good user experience
</bad>✅ Measurable outcomes
<good>
- All API endpoints return within 200ms
- Form validation provides instant feedback
</good>Full Workflow
For complete agent-centric workflow with parallel agents and validation: → workflows/convert-prd.md
For appspec style examples and when to use each: → references/appspec-styles.md
For annotated PRD examples showing good vs. problematic structure: → references/prd-examples.md
Convert PRD Workflow
Step-by-step process for transforming a PRD into an app_spec.txt.
Prerequisites
- PRD file path (will prompt if not provided)
- Output directory (defaults to
prompts/)
Step 1: Locate and Read PRD
1. If PRD path not provided, ask: "What is the path to your PRD file?"
2. Read the entire PRD file
3. Identify document structure (headers, code blocks, tables)Validate PRD contains:
- Project name/title
- Tech stack information
- Some form of feature/requirement description
- Implementation details or code examples
Step 2: Extract Project Metadata
Project Name
- Extract from first H1 heading
- Or from "Project:" field if present
- Clean to remove version numbers for the name
Overview
Synthesize a 3-5 sentence summary from:
- Any "Overview" section
- "Key Principles" or "Goals" sections
- Opening paragraphs describing purpose
Template:
Build a [type of system] that [primary purpose].
[Key architectural decision].
[Primary interface/usage pattern].
[Core value proposition].Step 3: Extract Technology Stack
Parse Tech Stack Table
Look for tables with columns like: | Component | Choice | Why |
Transform to:
<technology_stack>
<language>Python 3.11+</language>
<package_manager>uv</package_manager>
<core_dependencies>
<dependency name="ccxt">Exchange data fetching</dependency>
<dependency name="pandas">Data processing</dependency>
...
</core_dependencies>
</technology_stack>Include from Directory Structure
Reference directory layout for context on where code lives.
Step 4: Transform Data Models
From Pydantic → Schema Format
Input pattern:
class ModelName(BaseModel):
field: type = Field(constraint)
...Output pattern:
<table_name>
- field: type (constraint description)
- field2: type
...
</table_name>Transformation Rules
| Pydantic | App Spec |
|---|---|
Field(gt=0) | (positive) |
Field(ge=0) | (non-negative) |
Field(default=x) | (default: x) |
Optional[T] | nullable |
list[T] | array of T |
datetime | datetime |
@field_validator | Add constraint note |
Example Transformation
PRD:
class Candle(BaseModel):
timestamp: datetime
open: float = Field(gt=0)
high: float = Field(gt=0)
low: float = Field(gt=0)
close: float = Field(gt=0)
volume: float = Field(ge=0)App Spec:
<candles>
- timestamp: datetime
- open: float (positive)
- high: float (positive, must >= low)
- low: float (positive)
- close: float (positive)
- volume: float (non-negative)
</candles>Step 5: Extract Core Features
From Implementation Code → Feature Descriptions
Strategy: Read function/class docstrings and summarize behavior.
Input pattern:
def fetch_candles(config: FetchConfig) -> pd.DataFrame:
"""Fetch candles from exchange.
If config.since is provided, fetches historical data...
"""Output pattern:
<data_fetching>
- Fetch OHLCV candles from configurable exchange
- Support historical data via date parameter
- Validate trading pair exists on exchange
- Handle network errors with descriptive exceptions
</data_fetching>Group Features by Domain
Look for natural groupings:
- Data ingestion/fetching
- Processing/analysis
- Output/visualization
- CLI/API interface
- Configuration/settings
Step 6: Extract API/CLI Endpoints
From CLI Code → Command Summary
Input pattern:
@app.command()
def run(
symbol: str = typer.Argument("BTC/USDT"),
timeframe: str = typer.Option("4h", "-t"),
since: str = typer.Option(None, "--since"),
):
"""Run full pipeline: fetch → analyze → chart."""Output pattern:
<cli_commands>
- run [SYMBOL] -t TIMEFRAME --since DATE
Run full pipeline: fetch, analyze, and generate chart
- analyze-cmd [SYMBOL] --json
Fetch and analyze only, optional JSON output
</cli_commands>Include Library API
If library-first design, document importable functions:
<library_api>
- fetch_candles(config) -> DataFrame
- analyze(df, symbol, timeframe) -> Analysis
- generate_chart(df, analysis) -> Path
</library_api>Step 7: Transform Implementation Plan
From Epics/Tasks → Numbered Steps
Input pattern:
| E1 | Project Setup | 5 tasks | `uv sync` |
| E2 | Exception Hierarchy | 2 tasks | ... |Output pattern:
<implementation_steps>
<step number="1">
<title>Project Setup and Foundation</title>
<tasks>
- Initialize project with package manager
- Set up dependency file (pyproject.toml)
- Create directory structure
- Configure testing framework
- Verify setup with test collection
</tasks>
</step>
...
</implementation_steps>Consolidation Rules
- Merge small epics (2-3 tasks) into logical groups
- Aim for 6-10 implementation steps
- Each step should be a meaningful milestone
Step 8: Derive Success Criteria
Sources for Criteria
1. Test assertions:
assert len(df) == 50
assert df["high"].ge(df["low"]).all()→ "Data structure validation (OHLC relationships maintained)"
2. CLI usage examples:
# Output: BULLISH | PREMIUM | $98,400.00→ "Produces readable output with bias, zone, and price"
3. Key Principles from PRD:
- Library First
- Type Safety
- Testable→ Corresponding quality criteria
Structure Output
<success_criteria>
<functionality>
- Data fetching from exchange works reliably
- Analysis produces consistent, valid results
- Chart generation creates readable visualizations
</functionality>
<technical_quality>
- Type-safe data structures throughout
- Comprehensive error handling
- Test coverage for core modules
</technical_quality>
</success_criteria>Step 9: Assemble and Validate
Assemble Full Document
<project_specification>
<project_name>...</project_name>
<overview>...</overview>
<technology_stack>...</technology_stack>
<prerequisites>...</prerequisites>
<core_features>...</core_features>
<database_schema>...</database_schema>
<api_endpoints_summary>...</api_endpoints_summary>
<implementation_steps>...</implementation_steps>
<success_criteria>...</success_criteria>
</project_specification>Validation Checklist
- [ ] XML is well-formed (matching tags)
- [ ] No code snippets remain (converted to descriptions)
- [ ] All PRD sections have corresponding output
- [ ] Implementation steps are actionable
- [ ] Success criteria are measurable
Step 10: Write Output
1. Write to prompts/app_spec.txt (or user-specified path) 2. Report transformation summary:
Created app_spec.txt:
- Project: [name]
- Features: [N] groups
- Models: [N] tables
- Steps: [N] implementation phases
- Criteria: [N] success metricsTroubleshooting
PRD Missing Sections
If PRD lacks certain sections:
- No tech stack table: Extract from imports and comments
- No explicit features: Derive from function names and docstrings
- No implementation plan: Create from directory structure order
Ambiguous Transformations
When unsure how to transform: 1. Prefer declarative over procedural 2. Focus on WHAT not HOW 3. Keep constraints but remove implementation details 4. Ask user for clarification on critical decisions
Example Execution
User: Convert PRD.md to an app spec
Agent:
1. Reading PRD.md... (1522 lines)
2. Extracted: "SMC Chart Analysis Pipeline" v5.0
3. Found tech stack: Python 3.11+, uv, 9 dependencies
4. Converted 6 Pydantic models:
- Candle, CandleData, Analysis, FetchConfig...
5. Extracted 4 feature groups:
- data_fetching, analysis, charting, cli
6. Transformed 11 epics → 8 implementation steps
7. Derived 9 success criteria from tests
Writing to prompts/app_spec.txt...
Done!Related skills
Lark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.488k
Lark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.401k16.1kLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.397k16.1k
Domain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.318k202k
Opensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k71Readme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k71FAQ
What is the output format?
A structured app_spec.txt in XML with sections for overview, technology stack, features, schema, endpoints, steps, and success criteria.
How is a spec different from a PRD?
The PRD shows HOW (implementation details); the app spec describes WHAT (requirements and expectations) without dictating implementation.