Okwinds Miscellany AI Agent Prd

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

1. Generate a document skeleton:

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

2. Fill in using templates from references

3. 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

User-Agent Relationship Models

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.

2.4 Knowledge (RAG)

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

Per knowledge source, document:

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

See agent-patterns.md for detailed patterns.

Decision Framework

Define priority order for agent decisions:

1. Safety first
2. User intent
3. Efficiency
4. Quality

Conversation Design

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:

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:

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

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

Phase 6: Evaluation Framework

Goal: Define how to measure agent quality and success.

See evaluation-rubrics.md for detailed rubrics.

Core Metrics

Evaluation Methods

Phase 7: Operational Model

7.1 Cost Model

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:

Adding new capabilities:

1. Add reference file in references/
2. Update SKILL.md Resources section
3. 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.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.