AI Agent PRD Guide

Overview

Write PRDs for AI Agent products that define not just what the agent does, but how it thinks, decides, and acts.

Relationship with Other Skills

This skill extends prd-writing-guide for AI Agent products specifically. You should:

• Apply prd-writing-guide 's Seven Lenses to each agent capability

• Follow prd-writing-guide 's Writing Style Guide for requirement clarity

• Use prd-writing-guide 's Developer Test as your quality bar

Handoff: The Agent PRD this skill produces feeds into prd-to-engineering-spec for technical design. That skill includes an Agent-specific validation branch for converting agent capabilities into engineering specs.

Traditional PRD: Input → Deterministic Logic → Output Agent PRD: Goal → Perceive → Think → Decide → Act → Learn ↑ │ └───────── Feedback ────────┘

You're not defining a function. You're defining a cognitive architecture.

Quality Test

Can your engineering team answer these without asking you?

• What is the agent's purpose and identity?

• What capabilities (skills/tools) does it have?

• How does it decide what to do?

• What can it NOT do? (boundaries)

• When should humans intervene?

• How do we know if it's working well?

Quick Start

Generate a document skeleton:

bash scripts/generate_agent_prd_skeleton.sh ./docs/agent-prd "Customer Support Agent"

Fill in using templates from references

Validate completeness with checklist

Note: The skeleton generator writes a set of .md files into your output directory. Use a new/empty folder to avoid accidental overwrites.

Workflow

Phase 1: Agent Identity ──────► Who is the agent? What's its purpose? ↓ Phase 2: Capability Architecture ──► Skills, Tools, Memory, RAG, Workflows ↓ Phase 3: Behavior & System Prompt ─► How does it think? What's its DNA? ↓ Phase 4: Conversation Design ────► Golden conversations, example behaviors ↓ Phase 5: Safety & Guardrails ────► What can't it do? Human oversight? ↓ Phase 6: Evaluation Framework ───► How do we measure success? ↓ Phase 7: Operational Model ──────► Cost, scaling, iteration

Phase 1: Agent Identity

Goal: Define who the agent is and its relationship with users.

Key Elements

Element Questions to Answer

Persona Name, role, personality, expertise domain

Mission Why does this agent exist?

Boundaries What it IS vs what it is NOT

User Relationship Copilot, Autopilot, Peer, Expert, or Executor?

User-Agent Relationship Models

Model Description Example

Copilot Human leads, agent assists Code completion

Autopilot Agent leads, human monitors Customer support

Peer Equal collaboration Brainstorming

Expert Agent advises, human decides Medical advisor

Executor Human commands, agent executes Task automation

Phase 2: Capability Architecture

Goal: Define the building blocks that enable agent capabilities.

Capability Stack

┌─────────────────────────────────────────────────────────────────┐ │ SKILLS TOOLS WORKFLOWS │ │ (What it (External (Multi-step │ │ can do) actions) processes) │ │ └──────────────┼──────────────┘ │ │ ↓ │ │ AGENT CORE (Reasoning, Planning) │ │ ↓ │ │ ┌──────────────┼──────────────┐ │ │ MEMORY RAG CONTEXT │ │ (State/History) (Knowledge) (Awareness) │ └─────────────────────────────────────────────────────────────────┘

2.1 Skills

Reusable capability modules. See skills-specification.md.

Per skill, document:

• Purpose & trigger conditions

• Input/output specification

• Process logic

• Examples & boundaries

2.2 Tools

External actions the agent can invoke. See tools-specification.md.

Per tool, document:

• Interface definition (JSON schema)

• Execution details (endpoint, auth, timeout)

• Response handling

• Safety requirements (confirmation, audit)

2.3 Memory

Stateful, context-aware behavior. See memory-patterns.md.

Type Scope Example

Working Current request Context window

Session Current session Conversation history

Long-term Cross-session User preferences

2.4 Knowledge (RAG)

Knowledge grounding via retrieval. See memory-patterns.md for architecture patterns.

Per knowledge source, document:

Attribute Specify

Source What data source? (docs, DB, API, web)

Format Document types, data structure

Volume How much data? Growth rate?

Freshness Update frequency? Acceptable staleness?

Authority Is this authoritative? What if conflicting sources?

Retrieval configuration:

• Chunking strategy (semantic, fixed-size, hybrid) and chunk size rationale

• Embedding model and dimension

• Retrieval method (dense, sparse, hybrid) and top-k range

• Re-ranking strategy (if any)

• Quality threshold (minimum similarity score for inclusion)

Knowledge gap handling:

• How does the agent detect it doesn't know something?

• Response when knowledge is insufficient (admit? search? escalate?)

• Citation requirements (when must it cite? format? inline or footnote?)

Knowledge conflict resolution:

• When multiple sources disagree, which takes priority?

• Should the agent present conflicting views or choose one?

2.5 Workflows

Multi-step orchestrated processes. Document:

• Trigger and steps with success criteria

• Human checkpoints

• Timeout and cancellation handling

Phase 3: Behavior & System Prompt

Goal: Define how the agent thinks, decides, communicates—and encode it into a System Prompt specification.

Reasoning Strategies

Strategy Description Use When

ReAct Think → Act → Observe → Repeat Most tasks

Plan-then-Execute Full plan upfront → Execute Complex multi-step

Tree of Thought Explore multiple paths Exploration needed

Reflexion Self-critique and improve Quality-critical

See agent-patterns.md for detailed patterns.

Decision Framework

Define priority order for agent decisions:

• Safety first

• User intent

• Efficiency

• Quality

Conversation Design

Aspect Define

Voice & Tone Persona, formality, verbosity

Response Patterns By scenario (simple, complex, error, out-of-scope)

Multi-turn Context retention, topic switching, reference resolution

System Prompt Specification ⭐ Core Deliverable

The System Prompt is the agent's DNA. The PRD must produce a System Prompt Design Spec (not the final prompt text, but its design intent). See system-prompt-design.md.

Required sections in the System Prompt Spec:

Section Content Example

Identity Declaration Who the agent is, role, personality "You are Aria, a senior financial advisor..."

Capability Declaration What tools/skills are available, when to use each "You have access to: search_docs, calculate..."

Behavioral Instructions How to reason, when to ask vs act, output style "Always explain your reasoning before acting..."

Constraint Boundaries What the agent must never do "Never provide medical diagnoses..."

Output Format Rules Response structure, length, formatting "Use bullet points for lists of 3+..."

Escalation Rules When and how to hand off to humans "If user mentions legal action, transfer to..."

Phase 4: Example Conversations (Golden Conversations)

Goal: Define concrete conversation examples that serve as both behavioral spec and acceptance criteria.

See conversation-design.md for detailed methodology.

Why Golden Conversations Matter

For Agent products, example conversations are the most precise behavioral specification. They are:

• Acceptance criteria (does the agent behave like this example?)

• Training signals (few-shot examples in the system prompt)

• Evaluation dataset (automated quality testing)

• Stakeholder alignment tool (shows exactly what "good" looks like)

Coverage Requirements

Design golden conversations for each of these scenario types:

Scenario Type Count Purpose

Happy path 2-3 per use case Shows ideal agent behavior

Edge cases 1-2 per use case Shows boundary handling

Safety boundaries 3-5 total Shows refusal/escalation

Multi-turn complex 2-3 total Shows context management

Context switching 1-2 total Shows topic change handling

Error recovery 2-3 total Shows tool failure handling

Out-of-scope 2-3 total Shows graceful boundary enforcement

Conversation Annotation Format

Each golden conversation should include:

Conversation: [Scenario Name]

Type: [happy-path | edge-case | safety | multi-turn | error] Tests: [Which capabilities/rules this validates]

Dialogue

User: [input] Agent: [expected response] // Annotation: [Why this response is correct. What rules apply.]

User: [follow-up] Agent: [expected response] // Annotation: [Key behavior being demonstrated]

Unacceptable Alternatives

• Agent should NOT: [describe bad behavior]
• Agent should NOT: [describe bad behavior]

Evaluation Criteria

• [Checkable criterion 1]
• [Checkable criterion 2]

Phase 5: Safety & Guardrails

Goal: Define boundaries, controls, and human oversight.

See safety-checklist.md for comprehensive checklist.

5.1 Capability Boundaries

Category Document

CAN DO Authorized actions with conditions

CANNOT DO Prohibited actions with response

MUST ASK Actions requiring confirmation

5.2 Human-in-the-Loop

Define when humans must intervene:

• Approval triggers and workflow

• Escalation paths

• Override capabilities

5.3 Guardrails

Input Guardrails:

• Prompt injection protection

• Harmful request detection

• Input validation

Output Guardrails:

• Harmful content filtering

• PII leakage prevention

• Hallucination detection

5.4 Error Handling

Error Type Document

Tool failure Detection, message, recovery

Knowledge gap Detection, message, fallback

Reasoning failure Detection, restart/escalate

Phase 6: Evaluation Framework

Goal: Define how to measure agent quality and success.

See evaluation-rubrics.md for detailed rubrics.

Core Metrics

Dimension Metrics

Task Success Completion rate, first-turn resolution

Quality Accuracy, relevance, completeness

Safety Harmful response rate, boundary violations

Efficiency Latency, token usage, cost

User Experience CSAT, NPS, escalation rate

Evaluation Methods

Method Purpose Frequency

Automated Testing Regression, benchmarks Every change

Human Evaluation Quality assessment Weekly

LLM-as-Judge Scalable quality scoring Continuous

Red Team Testing Adversarial testing Quarterly

A/B Testing Compare variants As needed

Phase 7: Operational Model

7.1 Cost Model

Component Document

Per-request costs LLM tokens, embeddings, tool calls

Projected costs By scale (launch, 6 months, 1 year)

Cost controls Budgets, alerts, throttling

7.2 Scaling & Iteration

• Scaling strategy (horizontal, rate limiting, caching)

• Feedback collection mechanisms

• Continuous improvement cycle

• Version management

Output Structure

agent-prd/ ├── AGENT_PRD.md # Main document ├── IDENTITY.md # Agent persona & boundaries ├── USE_CASES.md # Users and use cases ├── SKILLS.md # Skills specification ├── TOOLS.md # Tools specification ├── MEMORY.md # Memory architecture ├── KNOWLEDGE.md # RAG configuration ├── WORKFLOWS.md # Workflow definitions ├── BEHAVIOR.md # Reasoning & conversation ├── SYSTEM_PROMPT_SPEC.md # System prompt design specification ⭐ ├── CONVERSATIONS.md # Golden conversations ⭐ ├── SAFETY.md # Guardrails ├── EVALUATION.md # Metrics & testing ├── EXAMPLES.md # Additional example interactions └── CHECKLIST.md # Completion checklist

Resources

Scripts:

• scripts/generate_agent_prd_skeleton.sh
• Generate PRD structure

Core References:

• references/agent-prd-template.md

• Complete PRD template

• references/skills-specification.md

• Skill definition guide

• references/tools-specification.md

• Tool definition guide

• references/memory-patterns.md

• Memory architecture patterns

• references/agent-patterns.md

• Reasoning & architecture patterns

• references/conversation-design.md

• Golden conversation methodology ⭐

• references/worked-example.md

• End-to-end worked example (HelpBot agent) ⭐

Safety & Evaluation:

• references/safety-checklist.md

• Safety requirements

• references/evaluation-rubrics.md

• Evaluation frameworks

Advanced Topics:

• references/multi-agent-design.md

• Multi-agent system design

• references/system-prompt-design.md

• System prompt engineering

• references/multimodal-design.md

• Multi-modal agent design

• references/observability-operations.md

• Monitoring & operations

• references/protocols-standards.md

• MCP, protocols, standards

• references/domain-specific-design.md

• Domain-specific guidance

Extensibility & Future-Proofing

This skill is designed to evolve with Agent technology:

Current Future-Ready

Text I/O Multimodal (vision, audio, video)

Single Agent Multi-Agent orchestration

Custom tools Protocol standards (MCP, Agent Protocol)

Basic metrics Full observability stack

Generic Domain-specific extensions

Adding new capabilities:

• Add reference file in references/

• Update SKILL.md Resources section

• Extend PRD template if needed

Summary: Agent PRD Principles

┌─────────────────────────────────────────────────────────────────┐ │ 1. DEFINE IDENTITY - Who is this agent? Not just features. │ │ 2. SPECIFY CAPABILITIES - Skills, Tools, Memory, Knowledge. │ │ 3. DESIGN THE PROMPT - System Prompt is the agent's DNA. │ │ 4. SHOW, DON'T TELL - Golden conversations are the spec. │ │ 5. BOUND THE BEHAVIOR - What it CAN'T do matters equally. │ │ 6. EVALUATE CONTINUOUSLY - Define metrics before building. │ │ 7. HUMANS IN THE LOOP - Know when to escalate, always. │ └─────────────────────────────────────────────────────────────────┘

The goal is to architect cognition—define how an intelligent system should think, decide, and act within safe boundaries.