build-prd
Skill6 starsChanged 29 days agoMITView on GitHub
Capture what you're building BEFORE writing it. Question-driven discovery that locks the target, success criteria, anchor case (one concrete example with expected outcome), and out-of-scope BEFORE any code, plan, or scaffolding. Output is `.claude/PRPs/{slug}/prd.md`. Use when starting a new skill, plugin, scorer, integration, deliverable template, or any artifact where "done" needs a verifiable definition. Triggers — "PRD for X", "spec out X", "let's plan a new skill/plugin", "build pipeline for X", "what are we actually building", or before any non-trivial build where you've caught yourself about to write code without a target. Pairs with build-probe (next), build-validate, build-plan, build-execute, build-evaluate.
In this repository30 other files it gives its agents.
- adversarial-re-readSkill
- adversarial-reviewSkill
- build-estimateSkill
- build-evaluateSkill
- build-executeSkill
- build-planSkill
- build-polishSkill
- build-probeSkill
- build-validateSkill
- excel-connector-governanceSkill
- five-whysSkill
- insight-builderSkill
- insight-crystallizerSkill
- insight-promotionSkill
- multi-sessionSkill
- notion-governanceSkill
- oodaSkill
- prd-writerSkill
- promote-to-toolingSkill
- quality-reviewSkill
- ralph-implementSkill
- ralph-loopSkill
- search-governanceSkill
- session-outputSkill
- skill-validatorSkill
- task-planSkill
- verifySkill
- voice-profile-testSkill
- why-diagnosticSkill
- writing-qualitySkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
If argument missing, ask the user for slug + one-sentence description.
- Very specific: line 33
Check: does .claude/PRPs/{slug}/prd.md already exist?
- Very specific: line 43
If no profile matches: proceed with the generic question set.
- Very specific: line 47
Use AskUserQuestion for closed-form items.
- Distinctive: line 106
BEFORE the Phase 6 checklist, and record the three answers under the PRD's Notes so the next reader sees what a stranger took from it.
- Very specific: line 123
If any box is [ ], edit the PRD before exiting.
- Distinctive: line 143
Keep the PRD to one page. Long PRDs hide vague anchors.
- Distinctive: line 145
Do NOT write code, plan, or scaffolding.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Build PRD
Codify what you're building BEFORE writing it. A build whose definition of "done" is vague will be done forever.
When to use
- Starting a new skill, plugin, scorer, integration, deliverable template, or any non-trivial artifact.
- Re-specifying an existing artifact after a scope change.
- Anytime you catch yourself about to write code without an explicit target and acceptance test.
When NOT to use
- Quick one-off scripts that won't ship and won't be re-run. Just write them.
- Bug fixes to existing code — the bug is the spec.
- Conversation-grade exploration. PRDs are for builds that will be run again.
Phase 1: PARSE
Extract from argument:
slug— kebab-case, ≤ 60 chars, unique within.claude/PRPs/- target type (skill, plugin, scorer, deliverable, integration, other)
If argument missing, ask the user for slug + one-sentence description.
Check: does .claude/PRPs/{slug}/prd.md already exist? If yes, refuse and tell the user — either edit the existing PRD or pick a new slug.
Phase 2: LOAD PROFILE + PARALLEL DISCOVERY READS
Batch in one message (independent reads, no dependencies):
Readprofile at.claude/PRPs/_profiles/{target-type}.mdif it existsGlob.claude/PRPs/*/prd.md— list past PRDs (anchor cases worth cross-referencing)Glob.claude/PRPs/*/evaluate.md— find prior FAIL verdicts on similar slugs (warnings)ReadCLAUDE.mdHard Rules section if the target type is "skill" or "plugin" (Rule 11 backlinks discipline applies)
If no profile matches: proceed with the generic question set. Flag in the PRD profile: none-loaded so build-plan and build-validate know to demand heavier review.
Phase 3: DISCOVERY (3–5 questions, batched)
Use AskUserQuestion for closed-form items. Use prose questions for the anchor.
Mandatory questions:
- What is this? One paragraph in plain English. What does the artifact DO from the user's perspective?
- Why does this matter? What decision or outcome rides on it? What gets worse if we don't build it (or build it wrong)?
- Anchor case. Name ONE concrete example: a specific input + the expected output/behavior. This is the verifiable "done" target. Vague anchors ("works well") are not acceptable.
- Success criteria. What measurable signals say this is built correctly? (e.g., "passes N fixture rows," "Shawn approves the first 3 outputs," "round-trips through tool X without errors")
- Out-of-scope. What should this artifact explicitly NOT do? List 2-3 things to prevent scope creep at execute time.
Profile-specific questions append to this list.
Phase 4: GROUND IN EXISTING WORK (parallel subagent fan-out)
Local Grep/Glob searches only your immediate working tree. The mirror target may live in any of: .claude/skills/, cowork/*/skills/, ~/gits/{sibling-repo}/.claude/skills/, ~/gits/{other-project-repo}/. Spawn an Explore subagent to find it efficiently across all of them:
Agent(
subagent_type="Explore",
description="Find mirror target for {target-type} build",
prompt="Find the closest existing {target-type} to what's described below. Search .claude/skills/, $HOME/gits/{this-repo}/cowork/*/skills/, $HOME/gits/{sibling-repo}/.claude/skills/. Return top 3 candidates with one-line rationale each, and excerpts of the most relevant frontmatter/headers. Search breadth: medium.\n\nBuild description: <paste discovery Q1 + Q2 answers>"
)The PRD should reference the top candidate verbatim as the mirror target. If the Explore returns weak matches, flag mirror: none — heavier adversarial review at validate time.
Phase 5: GENERATE
Copy .claude/PRPs/_templates/prd-template.md to .claude/PRPs/{slug}/prd.md. Fill every section. Empty sections must be marked TBD — block this build until filled, not silently omitted.
Phase 5.5: WRITING QUALITY PASS
Invoke writing-quality skill (rewrite mode) on the PRD's "What this is" and "Why this matters" sections before exiting. The PRD is a source document — Future-You and build-plan/build-validate will re-read it; AI-isms in the source compound into AI-isms in the artifact.
Skill(skill="writing-quality", args="rewrite .claude/PRPs/{slug}/prd.md sections 'What this is' and 'Why this matters'")Phase 5.6: COLD READ (the reader test)
The writing-quality pass checks sentences. It cannot tell whether the two prose sections say what
the build IS. Measured 2026-09-08 on yellow-sheet-1-2: every sentence passed that pass and the
sections were an evidence dump with no arc, no stakes and no sense of progress, caught only by the
owner on read. The author cannot run this test on their own text; a stranger can.
Spawn ONE agent with no repo context and hand it ONLY the text of "What this is" and "Why this matters" — paste the text; give it no file paths, no CLAUDE.md, no memories:
Agent(
subagent_type="general-purpose",
description="Cold read of the PRD summary",
prompt="You have no other context and may not read any file or run any tool. From the text below alone, answer in at most three sentences each: (1) What is being built, and where does it sit in the sequence of what came before it? (2) Why does it matter to the person who will use it — what is worse for them today? (3) What will be different when it is done? If the text does not let you answer one, write CANNOT ANSWER and name what is missing.\n\n<paste the two sections verbatim>"
)PASS = three answers, none CANNOT ANSWER, each naming something specific from the text (a
version, a person or role, a concrete change). A CANNOT ANSWER, or a generic answer ("it
improves the workbook"), is a rewrite of that section, not a note. Run it AFTER Phase 5.5 and
BEFORE the Phase 6 checklist, and record the three answers under the PRD's Notes so the next
reader sees what a stranger took from it.
Phase 6: VERIFY (tick through this checklist)
Re-read the generated PRD. Walk this checklist literally — tick each box yes/no in the output, do NOT skip silently:
- Anchor case names ONE concrete input (not a category, not "a typical case")
- Anchor case names an expected outcome concrete enough to grep / diff / visually compare
- Success criteria are measurable — each names a script, fixture, command, or named reviewer
- No success criterion contains "feels right", "high quality", "polished", or similar wish-words
- Out-of-scope lists 2-3 specific things (not "anything else")
- Mirror target named OR explicitly flagged "none exists"
- Acceptance checklist subsection populated with one
- [ ]per criterion + anchor case - Writing-quality pass run on "What this is" and "Why this matters" (Phase 5.5)
- Cold read passed: three answers, no
CANNOT ANSWER, recorded under Notes (Phase 5.6)
If any box is [ ], edit the PRD before exiting. Surface unresolved items to the user before printing the "Next step" line.
Output
## PRD Created: {target-type} — {short title}
**File:** .claude/PRPs/{slug}/prd.md
**Target type:** {skill / plugin / scorer / deliverable / integration / other}
**Profile:** {profile name or "generic (no profile)"}
**Anchor case:** {one-line summary}
### Next step
Prove the PRD's numbers before anyone plans against them: `build-probe {slug}` — offer to dispatch via `Skill(skill="build-probe", args="{slug}")` if user confirms.
Sequence: **prd → probe → validate → plan → estimate → build → evaluate**.Guidelines
- Question-driven; never assume the target. Asking 5 questions saves 5 hours of rework.
- Keep the PRD to one page. Long PRDs hide vague anchors.
- The template is the contract. Don't add new sections without updating the template.
- Do NOT write code, plan, or scaffolding. This skill produces a markdown PRD only.
- The slug is durable — it identifies this build across all subsequent skills (plan, validate, execute, evaluate).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

