Agent skill

agent-prompt-behavior

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.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/agent-prompt-behavior

SKILL.md

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

markdown
## 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

markdown
## 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

markdown
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

markdown
## 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

markdown
## 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

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results