prd-to-spec-skill
Fast MVP project foundation from a PRD or raw idea — docs/ specs, root AGENTS.md, implementation plan with cross-referenced IDs, ready for Claude Code / Codex / Cursor in one session. Built for small projects and vibe coding, not heavyweight delivery methods. Use when the user wants to set up project docs from a PRD, prepare a project foundation for AI coding agents, add missing docs, update living docs after a feature/tech/schema change, or audit drift between docs and code.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/heyncth--prd-to-spec-skill)HTML
<a href="/listings/heyncth--prd-to-spec-skill"><img src="/api/listings/heyncth--prd-to-spec-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Claude Code**
npx skills add heyncth/prd-to-spec-skill -a claude-code # or manually cp -r prd-to-spec-skill .claude/skills/ # project cp -r prd-to-spec-skill ~/.claude/skills/ # global
**Codex**
cp -r prd-to-spec-skill .agents/skills/ # project cp -r prd-to-spec-skill ~/.agents/skills/ # global
**Cursor / Copilot** — copy into `.agents/skills/` (Cursor also reads `.claude/skills/`; Copilot reads `.github/skills/`).
**Any agent via skills CLI**
npx skills add heyncth/prd-to-spec-skill -a claude-code -a codex -a cursor
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 120 lines
- ---
- name: prd-to-spec-skill
- description: Fast MVP project foundation from a PRD or raw idea — docs/ specs, root AGENTS.md, implementation plan with cross-referenced IDs, ready for Claude Code / Codex / Cursor in one session. Built for small projects and vibe coding, not heavyweight delivery methods. Use when the user wants to set up project docs from a PRD, prepare a project foundation for AI coding agents, add missing docs, update living docs after a feature/tech/schema change, or audit drift between docs and code.
- ---
- # PRD to Spec — Fast MVP Project Foundation
- Prepare the project foundation (docs + AGENTS.md + implementation plan) before coding starts: approval gates, two-round pushback, mechanical ID validation. Target: **MVP-ready foundation in one session** for small projects — not a full-product delivery method. Docs in English; talk to the user in their language.
- ## Non-negotiable rules
- 1. **No fabrication.** Missing critical information → ask the user. Never invent decisions on their behalf.
- 2. **No silent overrides.** Never overwrite or change a locked decision without approval.
- 3. **Two-round pushback.** When you find a gap, contradiction, or risky choice: state the problem + propose options (round 1). If the user rejects your recommendation on something that significantly affects the app, push back one more time with concrete risks and trade-offs (round 2). If the user still keeps their choice: respect it, log it to `DECISIONS_LOG.md` (decision, alternatives, reason, trade-offs, constraints, date), and move on. Never a third round.
- 4. **Research boundary.** During discovery and tech-stack selection, only search official docs / known solutions after asking the user for scope and constraints first. No broad searching when the current plan is already sound. The chain "self-debug → search GitHub issues, Stack Overflow, Reddit" belongs in `AGENTS.md` for the coding phase — not here.
- 5. **No empty files.** Conditional docs that do not apply are skipped or merged — never created empty.
- 6. **No mid-flight stops.** If you must pause (gate, question, error), say so explicitly. Track progress in a todo list; mark each file done as you finish it.
- 7. **Tag assumptions.** Anything you generated that the user did not explicitly confirm gets an inline `[ASSUMPTION: ...]` tag. Confirmed content carries no tag. Assumptions surface at every gate for one-click confirm-or-fix.
- ## Speed rules (this is an MVP skill)
- 1. **Default tier S.** Decide a document tier at Gate 0, announce it, let the user override:
- - **S (default, small/MVP project):** `PRD`, `USER_STORIES`, `USER_FLOWS`, `TECH_STACK`, `TDD`, `IMPLEMENTATION_PLAN`, `AGENTS.md` + conditional DB/API. Short files, no filler sections.
- - **M (added risk:** auth, payments, real user data): + fuller acceptance criteria, `UI_UX_SPEC` detail, error paths.
- - **L (rare):** only if the user asks or the project is genuinely multi-module. Never L by default.
- 2. **One question round, not a drip.** Discovery asks numbered questions in as few rounds as possible (target: 1–2). Every question carries a recommended answer so the user can accept it in one keystroke. Never ask a question whose prerequisite is unanswered.
- 3. **No research when the plan is sound** (rule 4). No re-interviewing what the PRD already answers.
- 4. **Gates are one line for tier S:** "Group G1 done, 3 files, validation clean — approve?" Not a wall of text.
- ## Modes
- Detect the project state first, announce the mode, and get confirmation before doing work (Gate 0).
- | Mode | Condition | Behavior |
- |---|---|---|
- | **New** | No `docs/` yet | Full generation flow below |
- | **Patch** | `docs/` exists | Only add missing parts or edit sections the user names. Never silently change locked decisions |
- | **Drift audit** | `docs/` + code exist | Compare docs vs code, produce a diff report with severity. Do not edit anything before approval |
- ## Execution flow
- ### Phase 0 — Intake & mode detect
- 1. Input:
- - **Existing PRD, complete** → read all of it before saying anything.
- - **Raw idea or thin PRD** → stop. Ask numbered clarifying questions in one round (speed rule 2): scope, users, constraints, risks, success criteria — each with a recommended answer. No output before answers.
- 2. Detect mode (New / Patch / Drift audit) from the repo state.
- 3. Announce mode + document tier (S/M/L) + planned outputs → get confirmation. **Gate 0.**
- ### Phase 1 — Discovery & findings report
- 1. Read everything: PRD, existing `docs/`, and current code (if any).
- 2. Produce a findings report covering: gaps, contradictions between sections, missing decisions, and risk areas (auth, data, core flows).
- 3. Ask scope/constraints before comparing options. Search official docs only after scope is clear (rule 4).
- 4. Apply two-round pushback (rule 3) for every significant finding.
- 5. **Readiness check before Gate 1** — answer all five; any NO = say so and fix before generating:
- - [ ] Requirements clear enough to write without inventing?
- - [ ] Tech stack decided (or proposed and confirmed)?
- - [ ] Data entities knowable from PRD/code?
- - [ ] Auth/safety boundary known?
- - [ ] Every open item tagged `[ASSUMPTION]` or answered?
- 6. **Gate 1:** user approves findings + recommendations + readiness verdict before any generation starts.
- ### Phase 2 — Generate (3 groups, 3 sub-gates)
- Copy the needed templates from `assets/templates/`, fill them, and place them in `docs/` (flat — no subfolders unless the project is genuinely large). `AGENTS.md` goes to the repo root.
- | Group | Files | Gate |
- |---|---|---|
- | G1 Foundation | `docs/PRD.md` → `docs/USER_STORIES.md` → `docs/USER_FLOWS.md` | Gate 1a |
- | G2 Spec | `docs/UI_UX_SPEC.md` → `docs/TECH_STACK.md` → `docs/TDD.md` → `docs/DATABASE.md` → `docs/API_SPEC.md` | Gate 1b |
- | G3 Plan & rules | `docs/IMPLEMENTATION_PLAN.md` → `AGENTS.md` | Gate 1c |
- Also in G3: if Claude Code is among the user's agents, write a root `CLAUDE.md` containing exactly `@AGENTS.md` — Claude Code does not read `AGENTS.md` directly in every version. One line, nothing else.
- Plan checkbox vocabulary: `[ ]` open · `[x]` done + verified · `[~]` reframed (approach changed, reason written under the task) · `[-]` skipped (reason written). `[~]` and `[-]` are always reported to the user, never applied silently.
- Conditional files: `docs/DATABASE.md` (skip if no database), `docs/API_SPEC.md` (skip if no API), `docs/TESTING.md` (only if complex logic needs a test plan), `docs/DECISIONS_LOG.md` (only if significant decisions/trade-offs occurred).
- **Depth by risk:** write deep detail for auth, data models, and core flows; keep CRUD and simple UI brief. Merge trivial sections instead of creating files.
- After G3: run `python assets/scripts/validate_ids.py` from the project root. Fix violations, re-run until clean. **Gate 2 (final):** summary of outputs + validation result for user approval.
- ### Phase 3 — Living-docs update (user changes feature / tech / schema)
- 1. Determine impact mechanically first: `python assets/scripts/validate_ids.py --impact REQ-xxx` (or `US/API/TBL` id) → reverse graph lists the stories, endpoints, tables, and plan tasks that reference it. Add manual judgment on top.
- 2. Present the impact list → get approval → edit only those files.
- 3. Re-run `validate_ids.py`.
- 4. Append to `DECISIONS_LOG.md` if the change involved a trade-off. A superseded decision is marked `superseded by D-xxx` — never rewritten or deleted.
- ### Phase 4 — Drift audit report
- Report only, no edits before approval. Each finding: file + line evidence (quote the actual line), docs side vs code side, severity:
- - **P0** — drift can cause data loss, security exposure, or a broken deploy
- - **P1** — blocks setup, a core flow, or API integration
- - **P2** — misleading docs an agent would act on wrongly
- - **P3** — naming, examples, polish
- Approved fixes go through Phase 3.
- ## ID scheme & validation
- | Prefix | Where | Rule |
- |---|---|---|
- | `REQ-xxx` | `PRD.md` | Core requirements |
- | `US-xxx` | `USER_STORIES.md` | Each story maps to ≥ 1 `REQ` |
- | `FLOW-xxx` | `USER_FLOWS.md` | Light — only main flows, no full coverage mandate |
- | `API-xxx` | `API_SPEC.md` | Each endpoint maps to ≥ 1 `REQ` or `US`, and matches `TBL` if a DB exists |
- | `TBL-xxx` | `DATABASE.md` | Tables |
- Mandatory checks (run by `validate_ids.py`): no duplicate IDs; no orphan `US`/`API`; `US` → `REQ`; `API` → `REQ`/`US`; `API` → `TBL` when both files exist. Do not invent ID systems beyond these. Implementation tasks use plain checkboxes `[ ]` / `[x]` referencing `REQ-xxx` — no task ID prefix.
- ## Output discipline
- - One job per doc file; no repetition across files.
- - Templates carry `<!-- REQUIRED -->` and `<!-- IF: condition -->` markers — drop markers and inapplicable sections before delivering.
- - Strip `[ASSUMPTION]` tags as the user confirms them; anything unconfirmed ships with the tag visible.
- - Never pad to look thorough; never cut critical detail to look short. Tier S files stay short by design.
- - Todo list tracks every file; report status at each gate.
README.md · README · 113 lines
- # prd-to-spec-skill
- > **MVP-ready project foundation in one session.**
- > PRD or raw idea → approved docs, `AGENTS.md`, implementation plan — ready for your coding agent.
- > Not a delivery method. Not a full-product framework. Preparation for small projects that need to start building today.
- [Agent Skills](https://agentskills.io) standard (`SKILL.md`) — works with Claude Code, Codex, Cursor, GitHub Copilot, and any skills-compatible agent.
- ## Why this exists
- Spec-kit, BMAD, and friends solve *"how to build a full product correctly"* — constitutions, per-feature loops, subagent reviews. Right for a 6-month build. Wrong for "I have an idea, give me docs today".
- `prd-to-spec-skill` occupies the other end:
- | You want | This skill |
- |---|---|
- | MVP / weekend project / small tool | ✅ default |
- | Docs in one session, then code | ✅ |
- | Nobody has time for 12 planning commands | ✅ |
- | Multi-quarter product with a team of agents | ❌ use [spec-kit](https://github.com/github/spec-kit) |
- ## Three pillars
- 1. **Understand** — read the PRD, find gaps, ask in *one numbered round with recommended answers*, challenge risky choices. Two-round pushback protocol: disagree once, disagree harder with trade-offs, then log your call and move on.
- 2. **Establish** — generate approved docs (tier **S by default** for MVP, M/L only when risk justifies it), cross-referenced with `REQ / US / API / TBL` IDs, validated by a script — not by vibes.
- 3. **Maintain** — re-run modes for living docs: impact analysis through the ID graph (`--impact REQ-001` → affected stories, endpoints, tables, tasks), Patch, and a P0–P3 drift audit. Docs never silently rot.
- **Human-approved decisions. AI-generated documentation. Continuously maintained context.**
- ## What makes it different
- - **Approval-first**: nothing is written as settled before you confirm it.
- - **Two-round pushback**: the agent must disagree with you — twice, with numbers — before obeying a risky choice.
- - **Mechanical cross-doc validation**: `validate_ids.py` fails on orphan/duplicate/broken `REQ→US→API→TBL` links. No other foundation skill ships a validator.
- - **`[ASSUMPTION]` tags**: anything the agent inferred but you never confirmed is visibly tagged until you confirm it. No silent fabrication.
- - **Graph-driven impact**: docs are a connected graph; changes propagate through it deterministically.
- ## What it generates
- | File | Scope |
- |------|-------|
- | `docs/PRD.md` | requirements `REQ-xxx` |
- | `docs/USER_STORIES.md` | stories `US-xxx` → `REQ` |
- | `docs/USER_FLOWS.md` | flows `FLOW-xxx` (light) |
- | `docs/UI_UX_SPEC.md` | screens, states |
- | `docs/TECH_STACK.md` | choices + rationale |
- | `docs/TDD.md` | technical design (architecture, data flow) |
- | `docs/DATABASE.md` | conditional — `TBL-xxx` |
- | `docs/API_SPEC.md` | conditional — `API-xxx` |
- | `docs/IMPLEMENTATION_PLAN.md` | checkboxes + `REQ` refs |
- | `AGENTS.md` (root) | 4 working rules for coding agents |
- | `docs/TESTING.md` | conditional — complex logic only |
- | `docs/DECISIONS_LOG.md` | conditional — significant decisions only |
- Conditional files are skipped when they don't apply — never created empty.
- ## Install
- **Claude Code**
- ```bash
- npx skills add heyncth/prd-to-spec-skill -a claude-code
- # or manually
- cp -r prd-to-spec-skill .claude/skills/ # project
- cp -r prd-to-spec-skill ~/.claude/skills/ # global
- ```
- **Codex**
- ```bash
- cp -r prd-to-spec-skill .agents/skills/ # project
- cp -r prd-to-spec-skill ~/.agents/skills/ # global
- ```
- **Cursor / Copilot** — copy into `.agents/skills/` (Cursor also reads `.claude/skills/`; Copilot reads `.github/skills/`).
- **Any agent via skills CLI**
- ```bash
- npx skills add heyncth/prd-to-spec-skill -a claude-code -a codex -a cursor
- ```
- ## Use
- ```
- /prd-to-spec-skill
- ```
- Paste your PRD or raw idea. The skill detects the mode (`New` / `Patch` / `Drift audit`), announces the document tier, asks one numbered round of questions with recommended answers, reports findings, and asks for approval before writing anything.
- Validation anytime:
- ```bash
- python assets/scripts/validate_ids.py <project-root> # full check
- python assets/scripts/validate_ids.py --impact REQ-001 . # what does this change affect?
- ```
- ## Example output
- [`examples/sample-output/`](examples/sample-output/) — a complete run for a small link shortener (Shrinkr): PRD → stories → flows → tech stack → TDD → DB → API → plan → `AGENTS.md` + `CLAUDE.md`. Validates clean and the `--impact` graph resolves `REQ-001 → US-001 → API-001 → TBL-001`.
- ```bash
- python assets/scripts/validate_ids.py examples/sample-output
- python assets/scripts/validate_ids.py --impact REQ-001 examples/sample-output
- ```
- ## Positioning (for the curious)
- Direct small skills (`code-idea`, `docs-ai-prd`, `ai-project-starter`) aim at general documentation; heavyweight kits (Spec Kit ~140k★, BMAD ~55k★, OpenSpec ~71k★) own the full-product lifecycle. This skill owns **fast preparation for small projects**: tier-S docs, one question round, gated approval, a validator, and lightweight living-docs maintenance.
- ## License
- Apache-2.0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.