Agent Prompt & Behavior

Build system prompts that provide deterministic cognitive control over AI agents.

What This Skill Does

Design agent system instructions with explicit behavior rules
Create intent-to-tool mapping tables (what user says → what agent does)
Define confirmation policies (when to ask before acting)
Establish error handling behaviors
Prevent hallucinated actions through grounding rules
Generate complete, production-ready system prompts

What This Skill Does NOT Do

Implement the agent runtime/executor
Handle conversation state management
Define API contracts or schemas
Deploy or test agents

Before Implementation

Gather context to ensure successful implementation:

| Source | Gather | |--------|--------| | Codebase | Available tools, existing prompts, agent framework | | Conversation | Agent's purpose, domain, user types | | Skill References | Prompt patterns, mapping rules, safety policies | | User Guidelines | Tone, brand voice, compliance requirements |

Core Principle: Cognitive Control

The system prompt is the agent's brain. It determines:

┌─────────────────────────────────────────────────────────────┐
│                    COGNITIVE CONTROL                        │
├─────────────────────────────────────────────────────────────┤
│  IDENTITY      │ Who am I? What's my purpose?              │
│  CAPABILITIES  │ What tools can I use? What can't I do?    │
│  BEHAVIOR      │ How do I respond? When do I confirm?      │
│  GROUNDING     │ What prevents me from hallucinating?      │
│  ERRORS        │ How do I handle failures gracefully?      │
└─────────────────────────────────────────────────────────────┘

Required Clarifications

Before building the system prompt, clarify:

1. Agent Identity

Purpose: What is this agent for? (task assistant, customer support, code helper)
Domain: What domain knowledge is needed?
Persona: Any personality traits or tone requirements?

2. Available Tools

Tool list: What tools/functions can the agent call?
Tool descriptions: What does each tool do?
Tool constraints: Any usage limits or conditions?

3. Safety Requirements

Destructive actions: Which actions need confirmation?
Forbidden actions: What must the agent never do?
Scope limits: What's out of scope?

4. Error Policy

Failure modes: How should the agent handle tool failures?
Ambiguity: What if user intent is unclear?
Escalation: When should agent defer to human?

System Prompt Architecture

A complete system prompt has 6 sections:

┌─────────────────────────────────────────┐
│ 1. IDENTITY & PURPOSE                   │
│    Who you are, what you do             │
├─────────────────────────────────────────┤
│ 2. CAPABILITIES & TOOLS                 │
│    What you CAN do (explicit list)      │
├─────────────────────────────────────────┤
│ 3. BOUNDARIES & CONSTRAINTS             │
│    What you CANNOT do (explicit list)   │
├─────────────────────────────────────────┤
│ 4. INTENT → TOOL MAPPING                │
│    How to interpret user requests       │
├─────────────────────────────────────────┤
│ 5. CONFIRMATION POLICY                  │
│    When to ask before acting            │
├─────────────────────────────────────────┤
│ 6. ERROR HANDLING                       │
│    How to handle failures gracefully    │
└─────────────────────────────────────────┘

See assets/system-prompt-template.md for complete template.

Intent-to-Tool Mapping

The most critical section. Maps natural language → deterministic action.

Mapping Table Format

## Intent Mapping

| User Says (Intent) | Tool to Call | Parameters | Confirmation |
|--------------------|--------------|------------|--------------|
| "create a task" | create_task | title, description | No |
| "delete task X" | delete_task | task_id | Yes |
| "show my tasks" | list_tasks | user_id | No |
| "mark X as done" | update_task | task_id, completed=true | No |

Mapping Rules

Be exhaustive: List ALL supported intents
Be specific: Avoid ambiguous mappings
Include variations: "delete", "remove", "get rid of" → same tool
Mark confirmations: Destructive actions need confirmation

See references/intent-mapping.md for patterns and examples.

Confirmation Policy

Actions Requiring Confirmation

| Category | Examples | Why Confirm | |----------|----------|-------------| | Destructive | Delete, remove, cancel | Irreversible | | Financial | Purchase, transfer, refund | Real money | | External | Send email, post message | Visible to others | | Bulk | Delete all, update all | Large impact |

Confirmation Format

Before I [action], let me confirm:
- [Detail 1]
- [Detail 2]

Proceed? (yes/no)

See references/confirmation-policy.md for implementation.

Grounding Rules (Prevent Hallucination)

Critical: The agent must ONLY use tools it actually has.

Grounding Principles

## Grounding Rules

1. ONLY call tools listed in your capabilities
2. NEVER invent tool names or parameters
3. If no tool matches the request, say so clearly
4. NEVER claim to have done something you didn't do
5. If a tool call fails, report the failure honestly

Unknown Intent Handling

When you receive a request you cannot fulfill:

1. Acknowledge the request
2. Explain what you CAN do instead
3. Offer alternatives if available
4. Never pretend or hallucinate capabilities

Error Handling Behavior

Error Response Pattern

## When Tools Fail

If a tool returns an error:
1. Do NOT retry automatically (unless specified)
2. Explain what happened in plain language
3. Suggest what the user can do
4. Offer to try an alternative approach

Example:
"I tried to create the task, but the database returned an error.
This might be a temporary issue. Would you like me to try again,
or would you prefer to wait a few minutes?"

Graceful Degradation

## Graceful Degradation

If you cannot complete a request:
1. Complete as much as possible
2. Clearly state what succeeded and what failed
3. Provide partial results if available
4. Suggest next steps

See references/error-handling.md for patterns.

Workflow: Building a System Prompt

1. CLARIFY
   └─→ Gather identity, tools, safety requirements

2. ENUMERATE TOOLS
   └─→ List all available tools with descriptions

3. MAP INTENTS
   └─→ Create intent → tool mapping table

4. DEFINE BOUNDARIES
   └─→ List forbidden actions and scope limits

5. SET CONFIRMATION POLICY
   └─→ Mark which actions need confirmation

6. ADD ERROR HANDLING
   └─→ Define failure responses

7. ASSEMBLE PROMPT
   └─→ Use template to create complete prompt

8. VALIDATE
   └─→ Check for gaps, ambiguities, conflicts

Anti-Patterns to Avoid

| Anti-Pattern | Problem | Better Approach | |--------------|---------|-----------------| | Vague capabilities | "Help with tasks" | List specific tools | | Missing boundaries | Agent tries anything | Explicit "do not" list | | No confirmation | Destroys data silently | Confirm destructive actions | | Silent failures | User thinks it worked | Always report errors | | Invented tools | Hallucinated actions | Grounding rules | | Ambiguous mapping | Wrong tool called | Specific intent patterns |

Output Checklist

Before delivering a system prompt:

[ ] Identity section defines purpose clearly
[ ] All available tools listed with descriptions
[ ] Intent → tool mapping is exhaustive
[ ] Boundaries and forbidden actions explicit
[ ] Confirmation policy covers destructive actions
[ ] Error handling defined for all failure modes
[ ] Grounding rules prevent hallucination
[ ] Unknown intent handling specified
[ ] Tone and persona consistent throughout

Reference Files

| File | When to Read | |------|--------------| | references/system-prompt-patterns.md | Prompt structure and examples | | references/intent-mapping.md | Intent recognition and mapping rules | | references/confirmation-policy.md | When and how to confirm actions | | references/error-handling.md | Failure modes and responses | | assets/system-prompt-template.md | Complete template to fill in |