Skip to content
Back to search

prd-to-spec-skill

SkillWorks with Claude CodeGitHub

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/heyncth--prd-to-spec-skill/badge.svg)](/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

i

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
  1. ---
  2. name: prd-to-spec-skill
  3. 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.
  4. ---
  5. # PRD to Spec — Fast MVP Project Foundation
  6. 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.
  7. ## Non-negotiable rules
  8. 1. **No fabrication.** Missing critical information → ask the user. Never invent decisions on their behalf.
  9. 2. **No silent overrides.** Never overwrite or change a locked decision without approval.
  10. 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.
  11. 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.
  12. 5. **No empty files.** Conditional docs that do not apply are skipped or merged — never created empty.
  13. 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.
  14. 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.
  15. ## Speed rules (this is an MVP skill)
  16. 1. **Default tier S.** Decide a document tier at Gate 0, announce it, let the user override:
  17. - **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.
  18. - **M (added risk:** auth, payments, real user data): + fuller acceptance criteria, `UI_UX_SPEC` detail, error paths.
  19. - **L (rare):** only if the user asks or the project is genuinely multi-module. Never L by default.
  20. 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.
  21. 3. **No research when the plan is sound** (rule 4). No re-interviewing what the PRD already answers.
  22. 4. **Gates are one line for tier S:** "Group G1 done, 3 files, validation clean — approve?" Not a wall of text.
  23. ## Modes
  24. Detect the project state first, announce the mode, and get confirmation before doing work (Gate 0).
  25. | Mode | Condition | Behavior |
  26. |---|---|---|
  27. | **New** | No `docs/` yet | Full generation flow below |
  28. | **Patch** | `docs/` exists | Only add missing parts or edit sections the user names. Never silently change locked decisions |
  29. | **Drift audit** | `docs/` + code exist | Compare docs vs code, produce a diff report with severity. Do not edit anything before approval |
  30. ## Execution flow
  31. ### Phase 0 — Intake & mode detect
  32. 1. Input:
  33. - **Existing PRD, complete** → read all of it before saying anything.
  34. - **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.
  35. 2. Detect mode (New / Patch / Drift audit) from the repo state.
  36. 3. Announce mode + document tier (S/M/L) + planned outputs → get confirmation. **Gate 0.**
  37. ### Phase 1 — Discovery & findings report
  38. 1. Read everything: PRD, existing `docs/`, and current code (if any).
  39. 2. Produce a findings report covering: gaps, contradictions between sections, missing decisions, and risk areas (auth, data, core flows).
  40. 3. Ask scope/constraints before comparing options. Search official docs only after scope is clear (rule 4).
  41. 4. Apply two-round pushback (rule 3) for every significant finding.
  42. 5. **Readiness check before Gate 1** — answer all five; any NO = say so and fix before generating:
  43. - [ ] Requirements clear enough to write without inventing?
  44. - [ ] Tech stack decided (or proposed and confirmed)?
  45. - [ ] Data entities knowable from PRD/code?
  46. - [ ] Auth/safety boundary known?
  47. - [ ] Every open item tagged `[ASSUMPTION]` or answered?
  48. 6. **Gate 1:** user approves findings + recommendations + readiness verdict before any generation starts.
  49. ### Phase 2 — Generate (3 groups, 3 sub-gates)
  50. 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.
  51. | Group | Files | Gate |
  52. |---|---|---|
  53. | G1 Foundation | `docs/PRD.md` → `docs/USER_STORIES.md` → `docs/USER_FLOWS.md` | Gate 1a |
  54. | G2 Spec | `docs/UI_UX_SPEC.md` → `docs/TECH_STACK.md` → `docs/TDD.md` → `docs/DATABASE.md` → `docs/API_SPEC.md` | Gate 1b |
  55. | G3 Plan & rules | `docs/IMPLEMENTATION_PLAN.md` → `AGENTS.md` | Gate 1c |
  56. 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.
  57. 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.
  58. 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).
  59. **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.
  60. 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.
  61. ### Phase 3 — Living-docs update (user changes feature / tech / schema)
  62. 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.
  63. 2. Present the impact list → get approval → edit only those files.
  64. 3. Re-run `validate_ids.py`.
  65. 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.
  66. ### Phase 4 — Drift audit report
  67. Report only, no edits before approval. Each finding: file + line evidence (quote the actual line), docs side vs code side, severity:
  68. - **P0** — drift can cause data loss, security exposure, or a broken deploy
  69. - **P1** — blocks setup, a core flow, or API integration
  70. - **P2** — misleading docs an agent would act on wrongly
  71. - **P3** — naming, examples, polish
  72. Approved fixes go through Phase 3.
  73. ## ID scheme & validation
  74. | Prefix | Where | Rule |
  75. |---|---|---|
  76. | `REQ-xxx` | `PRD.md` | Core requirements |
  77. | `US-xxx` | `USER_STORIES.md` | Each story maps to ≥ 1 `REQ` |
  78. | `FLOW-xxx` | `USER_FLOWS.md` | Light — only main flows, no full coverage mandate |
  79. | `API-xxx` | `API_SPEC.md` | Each endpoint maps to ≥ 1 `REQ` or `US`, and matches `TBL` if a DB exists |
  80. | `TBL-xxx` | `DATABASE.md` | Tables |
  81. 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.
  82. ## Output discipline
  83. - One job per doc file; no repetition across files.
  84. - Templates carry `<!-- REQUIRED -->` and `<!-- IF: condition -->` markers — drop markers and inapplicable sections before delivering.
  85. - Strip `[ASSUMPTION]` tags as the user confirms them; anything unconfirmed ships with the tag visible.
  86. - Never pad to look thorough; never cut critical detail to look short. Tier S files stay short by design.
  87. - Todo list tracks every file; report status at each gate.
README.md · README · 113 lines
  1. # prd-to-spec-skill
  2. > **MVP-ready project foundation in one session.**
  3. > PRD or raw idea → approved docs, `AGENTS.md`, implementation plan — ready for your coding agent.
  4. > Not a delivery method. Not a full-product framework. Preparation for small projects that need to start building today.
  5. [Agent Skills](https://agentskills.io) standard (`SKILL.md`) — works with Claude Code, Codex, Cursor, GitHub Copilot, and any skills-compatible agent.
  6. ## Why this exists
  7. 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".
  8. `prd-to-spec-skill` occupies the other end:
  9. | You want | This skill |
  10. |---|---|
  11. | MVP / weekend project / small tool | ✅ default |
  12. | Docs in one session, then code | ✅ |
  13. | Nobody has time for 12 planning commands | ✅ |
  14. | Multi-quarter product with a team of agents | ❌ use [spec-kit](https://github.com/github/spec-kit) |
  15. ## Three pillars
  16. 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.
  17. 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.
  18. 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.
  19. **Human-approved decisions. AI-generated documentation. Continuously maintained context.**
  20. ## What makes it different
  21. - **Approval-first**: nothing is written as settled before you confirm it.
  22. - **Two-round pushback**: the agent must disagree with you — twice, with numbers — before obeying a risky choice.
  23. - **Mechanical cross-doc validation**: `validate_ids.py` fails on orphan/duplicate/broken `REQ→US→API→TBL` links. No other foundation skill ships a validator.
  24. - **`[ASSUMPTION]` tags**: anything the agent inferred but you never confirmed is visibly tagged until you confirm it. No silent fabrication.
  25. - **Graph-driven impact**: docs are a connected graph; changes propagate through it deterministically.
  26. ## What it generates
  27. | File | Scope |
  28. |------|-------|
  29. | `docs/PRD.md` | requirements `REQ-xxx` |
  30. | `docs/USER_STORIES.md` | stories `US-xxx` → `REQ` |
  31. | `docs/USER_FLOWS.md` | flows `FLOW-xxx` (light) |
  32. | `docs/UI_UX_SPEC.md` | screens, states |
  33. | `docs/TECH_STACK.md` | choices + rationale |
  34. | `docs/TDD.md` | technical design (architecture, data flow) |
  35. | `docs/DATABASE.md` | conditional — `TBL-xxx` |
  36. | `docs/API_SPEC.md` | conditional — `API-xxx` |
  37. | `docs/IMPLEMENTATION_PLAN.md` | checkboxes + `REQ` refs |
  38. | `AGENTS.md` (root) | 4 working rules for coding agents |
  39. | `docs/TESTING.md` | conditional — complex logic only |
  40. | `docs/DECISIONS_LOG.md` | conditional — significant decisions only |
  41. Conditional files are skipped when they don't apply — never created empty.
  42. ## Install
  43. **Claude Code**
  44. ```bash
  45. npx skills add heyncth/prd-to-spec-skill -a claude-code
  46. # or manually
  47. cp -r prd-to-spec-skill .claude/skills/ # project
  48. cp -r prd-to-spec-skill ~/.claude/skills/ # global
  49. ```
  50. **Codex**
  51. ```bash
  52. cp -r prd-to-spec-skill .agents/skills/ # project
  53. cp -r prd-to-spec-skill ~/.agents/skills/ # global
  54. ```
  55. **Cursor / Copilot** — copy into `.agents/skills/` (Cursor also reads `.claude/skills/`; Copilot reads `.github/skills/`).
  56. **Any agent via skills CLI**
  57. ```bash
  58. npx skills add heyncth/prd-to-spec-skill -a claude-code -a codex -a cursor
  59. ```
  60. ## Use
  61. ```
  62. /prd-to-spec-skill
  63. ```
  64. 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.
  65. Validation anytime:
  66. ```bash
  67. python assets/scripts/validate_ids.py <project-root> # full check
  68. python assets/scripts/validate_ids.py --impact REQ-001 . # what does this change affect?
  69. ```
  70. ## Example output
  71. [`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`.
  72. ```bash
  73. python assets/scripts/validate_ids.py examples/sample-output
  74. python assets/scripts/validate_ids.py --impact REQ-001 examples/sample-output
  75. ```
  76. ## Positioning (for the curious)
  77. 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.
  78. ## License
  79. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.