| name | docs-ai-prd |
| description | Writes PRDs and specs optimized for coding assistants. Use when authoring requirements or project context for Claude Code, Cursor, Copilot, or Codex. |
| compatibility | Portable core. Works on Claude Code and Codex. |
| version | 1.1 |
| last_validated | 2026-07-11T00:00:00.000Z |
PRDs, Specs, and Project Context
Use this skill to create decision-first PRDs, tech specs, acceptance criteria, and tool-aware project context for coding assistants.
This skill owns what the implementation agent needs to know and how that context should be structured. It does not own general documentation cleanup or canonical docs maintenance.
Workflow
- Pick the deliverable.
- Gather evidence, constraints, and dependencies.
- Choose the canonical context surface for the target tool or team workflow.
- Write decisions first.
- Add acceptance criteria, rollout gates, and source-backed facts.
- Validate with the relevant checklist before handoff.
ASCII Flow
Request
|
v
Classify deliverable
|-- PRD / brief -------------------> assets/prd/
|-- technical spec ----------------> assets/spec/
|-- story / acceptance criteria ---> assets/stories/
|-- agent handoff context ---------> assets/planning/ + tool context files
|
v
Gather evidence + constraints + dependencies
|
v
Choose context surface
|-- Claude Code -----> CLAUDE.md / scoped Claude files
|-- Codex -----------> AGENTS.md / scoped instructions
|-- Copilot ---------> .github/copilot-instructions.md
|-- Cursor ----------> .cursor/rules/ or AGENTS.md
|
v
Write decisions first
|
v
Add measurable acceptance criteria + rollout / rollback gates
|
v
Validate paths, claims, risks, and handoff readiness
Quick Reference
Defaults
- decision-first beats narrative-first
- acceptance criteria must be binary or measurable
- AI features need evals, rollback rules, and permission boundaries
- shared context should stay small; tool-specific behavior belongs in tool-specific files
- cross-tool portability is useful, but no single context file is universal
Expert Judgment: Why Specs Fail Coding Agents
Checklists catch missing sections. They do not catch the judgment calls that make the difference between a spec an agent can execute unattended and one that silently produces the wrong thing while satisfying every checklist item. Apply this before handoff, especially for agentic/autonomous runs where no reviewer sees the intermediate state.
Ambiguity classes that kill agent runs
A non-expert reviewer reads a spec for completeness of sections. An expert reads it for these six ambiguity classes, because each one lets a competent agent produce plausible-looking, contract-breaking output while technically following the text:
- Referential ambiguity — "the user," "the form," "it" without a fixed noun-phrase, ID, or schema reference. The agent binds to the nearest plausible referent, which is wrong for the case the author had in mind.
- Silent-default ambiguity — a case is never mentioned (duplicate email, empty list, concurrent edit), so the agent invents a default. That default is rarely audited against the rest of the system.
- Scope-boundary ambiguity — the spec describes new behavior but never states what must stay unchanged. Agents over-refactor adjacent code or leave a now-dead path that nobody asked them to remove.
- Temporal/ordering ambiguity — steps are implied but not sequenced ("validate and save" — validate before or after the side effect that can't be undone?).
- Measurement ambiguity — "fast," "reliable," "secure," "clean" with no unit, threshold, percentile, or test method attached.
- Authority ambiguity — the spec and the existing code disagree, and nothing states which one wins. The agent picks one; the next agent (or the next session) may pick the other.
When reviewing a draft spec, scan specifically for these six classes rather than re-reading for tone or completeness — completeness checklists (see references/requirements-checklists.md) do not surface any of them.
Over-specification vs. under-specification: the calibration judgment
Both failure modes are common, and they look opposite but come from the same root cause: guessing the right level of detail instead of deriving it from risk.
- Over-specification dictates implementation (a named library, exact variable names, line-level pseudocode) when only the outcome mattered. Cost: the agent thrashes when the mandated approach doesn't fit the codebase, or ships literally what was written instead of what was meant, and the mismatch isn't visible until review.
- Under-specification gives a title and one paragraph and leaves every non-happy-path implicit. Cost: the agent invents contract details (error shape, retry count, empty-state behavior) that conflict with assumptions already baked into three other call sites — expensive to discover after the fact, not before.
Calibrate detail level to three variables, not to habit or template length:
| Blast radius | Reversibility | Agent autonomy | Right level of detail |
|---|
| High (payments, auth, deletion, PII) | Low (hard to roll back) | Any | Spec every edge case explicitly, plus a "must NOT" list |
| Medium | Medium | Supervised turn-by-turn (human reviews each step) | State decisions + open questions; let the review loop resolve remaining edge cases |
| Low (prototype, internal tool, behind a flag) | High (cheap to revert) | Any | Outcome + happy path; let the agent propose and flag edge cases |
| Medium or High | Any | Unattended/autonomous run (no human in the loop until done) | Spec every edge case — there is no reviewer to catch drift mid-run |
The common mistake is applying "prototype-level" detail to an unattended, high-blast-radius run, or applying "payments-level" detail to a two-hour supervised prototype. Ask blast radius and autonomy first; let those answers set the spec's length, not the other way around.
Acceptance-criteria testability: the judgment beyond the checklist
references/acceptance-criteria-patterns.md covers format and common mistakes. Two judgment calls sit above that checklist:
- The "can't picture the failing test" tell. An AC that reads well but generates zero tests is unfalsifiable. If you cannot describe the specific test that would fail if the behavior were wrong, the AC is not done — rewrite it before handoff, don't ship it and hope the agent infers the missing half.
- The "two competent engineers" tell. The most common single point of spec failure is not a missing AC — it's an AC that is simultaneously true for two materially different implementations. Ask: "could two competent engineers build different things and both honestly claim this AC is satisfied?" If yes, add a discriminating clause (a concrete input/output pair, a specific error code, an explicit ordering) until the answer is no.
Cross-Tool Context Rules
Treat project memory as layered:
| Tool | Primary Surface | Supporting Surfaces |
|---|
| Claude Code | CLAUDE.md | scoped Claude files, agents, skills, hooks |
| GitHub Copilot | .github/copilot-instructions.md | additional GitHub instructions, AGENTS.md |
| Cursor | .cursor/rules/ or root AGENTS.md | root CLAUDE.md, scoped rule files |
| portable baseline | AGENTS.md | link outward instead of duplicating deep guidance |
Quality Gates
PRD and spec quality
- clear problem statement and evidence
- named owner and success criteria
- measurable acceptance criteria
- metrics with formula, timeframe, and source
- explicit risks, rollout gates, and rollback conditions
AI feature quality
- baseline alternative documented
- eval objective and dataset plan defined before build
- permission, prompt-injection, and data-exfiltration risks covered
- monitoring, incident response, and kill switch specified
Project-context quality
- file paths and commands match the repo
- guidance is routed to the correct tool surface
- no secrets or sensitive data
- shared and tool-specific instructions do not conflict
Navigation
References — Core (load first)
References — Spec-driven & prompt craft
References — Codebase context extraction
References — Stakeholder & team process
Additional assets
Output Format: HTML vs Markdown for Spec Artifacts
Markdown is the default for most context-file surfaces (CLAUDE.md, AGENTS.md, .cursor/rules/), but it is not always the right format for the human-facing artifacts this skill produces (PRDs, tech specs, exploration docs, planning briefs, code-review writeups). For artifacts intended to be read by humans rather than parsed by the next agent, consider HTML.
This guidance is based on Thariq, Using Claude Code: The Unreasonable Effectiveness of HTML (Claude Code team, 2026-05-08).
When HTML wins over Markdown
- The artifact will exceed ~100 lines and needs to actually be read by stakeholders (most PRDs and tech specs cross this threshold).
- The spec benefits from visual structure: tables, SVG diagrams, color-coded findings, side-by-side comparisons, annotated code diffs.
- The artifact will be shared via link (S3, internal storage) rather than read in a repo viewer.
- The spec is exploratory — multiple design options compared in a grid, mockups, data-flow diagrams.
- The artifact is interactive — sliders, drag-drop reordering, form-based configuration with a "copy as JSON / prompt / diff" export button at the end.
When Markdown still wins
- Agent-consumed context files (
CLAUDE.md, AGENTS.md, .cursor/rules/) stay markdown — agents parse markdown reliably and HTML adds no signal for them.
- Artifacts that live in version control and need clean diffs — HTML diffs are noisy and hard to review.
- Short artifacts (≤100 lines) where added expressiveness is not worth the 2–4× generation cost.
- Acceptance criteria meant to be evaluated programmatically (Gherkin, JSON Schema), where structure matters more than rendering.
Concrete tradeoffs
| Dimension | Markdown | HTML |
|---|
| Generation time | Baseline | 2–4× longer |
| Token cost | Lower | Higher (frontier large-context models absorb it for most artifacts) |
| Read-through likelihood for >100-line specs | Low — author of Thariq's article reports "I tend to not actually read more than a 100-line markdown file" | Much higher — visual structure invites reading |
| Shareability | Poor — most browsers don't render natively | Excellent — upload + link |
| Version-control diffs | Clean | Noisy |
| Interactive elements | None | Sliders, drag-drop, forms, copy buttons |
| Agent re-ingestion | Native | Works, but markdown is denser per token |
The export-button pattern (interactive specs)
When generating an interactive HTML artifact, always end with an export control: "copy as JSON", "copy as prompt", "copy diff", "copy as markdown". The button turns UI manipulation back into pasteable text that closes the loop into the next prompt or PR description. Interactive specs without an export button create a one-way artifact the user can't act on.
Recipe — HTML spec authoring
- Decide format up front based on the table above. Default to markdown for context-file surfaces; default to HTML for read-once human artifacts >100 lines.
- For HTML, point Claude at the codebase's existing UI or design system. Maintain one design-system HTML file per project that other HTML artifacts can reference to match company style.
- For exploration specs, request a grid layout with multiple options side-by-side, each labeled with the tradeoff it makes.
- For interactive HTML, specify the export control explicitly in the prompt — do not assume the agent will add it.
- For implementation handoff, write the HTML spec for the human reviewer; then in the next session, pass the HTML file to the implementation agent along with markdown acceptance criteria. The implementation agent gets binary criteria; the human gets the richer artifact.
Related skills
- Interactive HTML with controls + export button:
../playground:playground (interactive playground pattern is the same shape)
- Frontend design for matching company style:
frontend-design:frontend-design plugin skill
- Plan output format selection (HTML vs markdown for plan documents):
../dev-workflow-planning/SKILL.md
What not to do
- Do not build a forced
/html skill or rule that everything must be HTML — Thariq's own caution. Prompting fluency beats a forced abstraction.
- Do not put PRDs and context files in the same format by default — the right format depends on the audience (human vs agent).
- Do not lose acceptance criteria in HTML decoration — the binary, measurable parts must remain extractable, ideally as a code block or table the implementation agent can parse cleanly.
Boundary: docs-ai-prd vs docs-codebase
docs-ai-prd owns requirements, specs, acceptance criteria, and context-file strategydocs-codebase owns README, runbooks, API reference, changelogs, and canonical documentation quality
If you are deciding what context an agent needs or how a spec should be structured, stay here. If you are rewriting repository docs, use docs-codebase.
Related Skills
Fact-Checking
- Verify volatile vendor, standard, and tool-behavior claims before final advice.
- Prefer primary sources and the curated
data/sources.json registry.
- If live verification is unavailable, mark external claims as unverified.
Learnings Loop
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
