writing-prd
Skill2 starsChanged 3 months agoMITView on GitHub
Author product requirements — PRDs, product specs, one-pagers, PR-FAQs, product briefs — that lead with the problem, define testable success metrics and acceptance criteria, and make non-goals explicit. Use when the user asks to write a PRD, write/define product requirements, write a product spec, write a one-pager, write a PR-FAQ, "write a spec", "define requirements", scope a feature, or draft a product brief. Also use when the request is a half-baked feature idea that needs a problem framed before any solution. Not for engineering design docs / the technical "how" — that is a separate design doc (the PRD owns the what/why, the design doc owns the how).
2 other projects use a version of this.
Adopted by
Most recently taken up by
- jiangxidong/pm-ostheir own version, first seen Oct 20, 2026
- SayandipBagchi/prd-buildertheir own version, first seen Sep 14, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- jiangxidong/pm-os★ 1same name
- SayandipBagchi/prd-builder★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository19 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- api-designSkill
- building-frontend-uiSkill
- debugging-agent-runsSkill
- developing-featuresSkill
- developing-features-tddSkill
- documenting-featuresSkill
- ensuring-cross-platformSkill
- evaluating-ai-outputSkill
- exploratory-testingSkill
- fixing-bugsSkill
- playwright-cliSkill
- reviewing-codeSkill
- running-agent-loopsSkill
- security-reviewSkill
- threat-modelingSkill
- validating-in-realitySkill
- writing-pull-requestsSkill
- writing-testsSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 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.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
If learnings/ holds only its README, proceed with the defaults below.
- Distinctive: line 25
Problem before solution, always: Write the section skeleton from references/prd-structure.md.
- Distinctive: line 45
Never collapse the design doc into the PRD.
- Distinctive: line 59
Problem before solution: No solution section is complete until the problem section cites evidence.
- Distinctive: line 61
Every metric needs a target and a timeframe: No bare directions ("more", "better").
- Very specific: line 65
Don't invent numbers: If you lack a real target, mark it TBD and flag it — don't fabricate.
- Very specific: line 70
Before closing, ask: *did I encounter a section template, required metric, approval workflow, non-goal convention, or product-area quirk …
≈ “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
Writing a PRD
Produce a product requirements artifact that states the problem before the solution, ties to a measurable outcome, makes non-goals explicit, and defines acceptance criteria a team can test. The PRD is the what and why; the how belongs in a separate engineering design doc. Match the artifact's weight to the bet's scope and risk — a one-pager for a small change, a full PRD for a new product, a PR-FAQ for a strategic bet whose desirability is unproven.
Read first (always)
List learnings/ and read every file relevant to the current product area, team, or artifact type. Project-specific section templates, required metrics, approval workflows, naming, or "what counts as a non-goal here" live there and override the defaults in this SKILL.md. If a learning conflicts with this file, the learning wins — mention it to the user.
If learnings/ holds only its README, proceed with the defaults below.
Workflow
- Decide whether — and what — to write. Run a lightweight opportunity assessment before committing to a heavy artifact. Use the SVPG/Cagan 10 questions (Inspired, Marty Cagan): what problem, for whom, how big is the opportunity, what alternatives exist, why are we best suited, why now, how will we go to market, how will we measure success, what are the critical factors to succeed, and — given all that — what is the recommendation. For strategic or ambiguous bets where desirability/viability is unproven, write the Amazon PR-FAQ first (see references/pr-faq.md). → verify: you can state the problem and the target user in one sentence each, without naming a solution.
- Pick the artifact weight. One-pager / mini-PRD for a small, well-understood change (roughly < 2 weeks, one team). Full PRD for a new product, cross-functional work, or higher risk/ambiguity. PR-FAQ for a strategic bet where the value is not yet validated. When in doubt, start lighter and grow the artifact — never start with a heavyweight template for a small change. → verify: the weight matches scope, risk, and audience; you can justify the choice in one line.
- Problem before solution, always. Write the section skeleton from references/prd-structure.md. Fill the problem statement, evidence, and target users before describing any solution. If you cannot articulate the problem with evidence, stop and go back to step 1. → verify: the problem statement cites evidence (data, research, support tickets, quotes) — not an assumption.
- Define success metrics and testable acceptance criteria. Pick a North Star and leading/lagging metrics with a target and timeframe each, plus guardrail/counter-metrics. Write acceptance criteria in Given/When/Then, behavior-not-implementation, covering edge/boundary/error cases. Keep acceptance (did we ship it right?) separate from success (did it move the outcome?). See references/metrics-and-acceptance.md. → verify: every metric has a number and a date; every requirement maps to at least one testable acceptance criterion.
- Lint against the anti-patterns (below) before sharing. Walk the list explicitly. The most common gap between a good and a great PRD is a missing or weak non-goals section. → verify: each anti-pattern checked off; non-goals section is present and specific.
The artifact ladder
Match weight to scope, risk, and audience — escalate only when the bet warrants it.
| Artifact | When | Owns |
| One-pager / mini-PRD | Small, well-understood change; one team; low risk | what / why |
| Full PRD | New product; cross-functional; higher risk or ambiguity | what / why |
| PR-FAQ | Strategic bet; desirability/viability unproven | what / why |
| Engineering design doc | The technical how — architecture, data model, APIs | how (separate) |
Never collapse the design doc into the PRD. The PRD answers what should be true and why; the design doc answers how we will build it. Conflating them buries product decisions under technical ones and makes both harder to review.
Anti-patterns — lint before sharing
- Solutionizing before a validated problem. A solution written before the problem is evidenced. Fix: lead with problem + evidence; defer the solution.
- No metrics, weak metrics, or vanity metrics. "Increase engagement" with no number, or counting signups that never activate. Fix: North Star + leading/lagging, each with a target and timeframe; add guardrails. See references/metrics-and-acceptance.md.
- Missing non-goals / out-of-scope. The #1 gap between a good and a great PRD. Without it, scope creeps and reviewers argue about things you never intended to do. Fix: list explicitly what this will not do — and, where useful, why.
- Ambiguous or untestable requirements. "It should be fast", "intuitive UX". Fix: rewrite as Given/When/Then with concrete, measurable conditions.
- Conflating acceptance with success criteria. Treating "we shipped the feature" as proof the outcome moved. Fix: acceptance = built correctly (binary, per requirement); success = outcome moved (metric vs. target over time). Keep them in separate sections.
- Over-rigid spec with no room to learn. A locked spec that forbids discovery during build. Fix: state the problem and outcome firmly; hold the solution detail loosely where the team should still learn. Mark open questions with an owner and a resolution date.
- Smuggling the how into the PRD. Architecture, schemas, library choices. Fix: move them to the design doc; the PRD references it.
Hard rules
- Problem before solution. No solution section is complete until the problem section cites evidence.
- Non-goals are mandatory in a full PRD; recommended in a one-pager.
- Every metric needs a target and a timeframe. No bare directions ("more", "better").
- Acceptance ≠ success. Two distinct sections, never merged.
- The PRD is the what/why. Defer the how to a linked engineering design doc.
- English only, regardless of conversation language.
- Don't invent numbers. If you lack a real target, mark it
TBDand flag it — don't fabricate. - No commits. Print the PRD in chat or write to the planned path only if the user asks to save; never run
git commit/add/push.
Capture a learning (final step)
Before closing, ask: did I encounter a section template, required metric, approval workflow, non-goal convention, or product-area quirk not in this SKILL.md or references/? If yes, append a learnings/YYYY-MM-DD-slug.md (protocol in learnings/README.md). If no, skip.
See also
- references/prd-structure.md — the canonical PRD section skeleton with one line of guidance each, plus the artifact ladder.
- references/metrics-and-acceptance.md — success metrics, acceptance vs. success criteria, and prioritization frameworks (RICE, MoSCoW, Kano, Impact/Effort).
- references/pr-faq.md — the Amazon Working Backwards PR-FAQ template and when to use it.
../documenting-features/references/communication.md— answer-first structure (Minto Pyramid / SCQA); lead the PRD with the recommendation, not the build-up.documenting-featuresskill — the living-doc companion: once the feature ships, the PRD's problem/scope/criteria feed the feature doc.developing-featuresskill — turns the PRD's acceptance criteria into implementation and tests.learnings/— project-specific PRD conventions accumulated over time.
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.

