agent-prompt-behavior

name	agent-prompt-behavior
description	Design agent system prompts with explicit behavior rules and cognitive control. This skill should be used when users need to define agent instructions, create intent-to-tool mappings, establish confirmation policies, or prevent hallucinated actions in AI agents.

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

1. Be exhaustive: List ALL supported intents
2. Be specific: Avoid ambiguous mappings
3. Include variations: "delete", "remove", "get rid of" → same tool
4. 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