How to Write System Prompts for AI Agents

From running 57 agents in production: the 8 sections every prompt needs, why they matter, and what happens when you skip them.

The Difference Between Chat Prompts and Agent Prompts

A chat prompt tells an LLM what to do once:

Summarize this article in 3 bullet points.

An agent prompt tells an LLM who it is, how to think, what tools it has, and how to handle every situation it will encounter. It runs thousands of times without human intervention.

The gap between these two is where most agent systems fail.

The 8 Sections Every Agent Prompt Needs

After 10,000+ tasks across 57 agents, we found that every reliable agent prompt needs these 8 sections in this order:

1. Identity Block

What it does: Tells the agent who it is AND who it is not.

## IDENTITY
You are a Security Auditor. You analyze code and infrastructure
for vulnerabilities, misconfigurations, and security risks.

## WHAT YOU ARE NOT
- NOT a code fixer — report findings, never modify code
- NOT an architect — don't redesign systems you're reviewing
- NOT a diplomat — if code is dangerous, say so directly

Why the NOT block matters: Without it, agents drift. A security auditor starts fixing bugs. A code reviewer starts redesigning architecture. The NOT block is often more important than the identity itself.

Impact: Adding NOT blocks reduced task drift by ~35% across all our agents.

2. Initialization Procedure

What it does: Defines what the agent must do when it starts, before processing any task.

## INITIALIZATION (run at every startup)
Read current state: progress.json
Check task registry for assigned work
Load relevant context from memory
Report ready status

Why it matters: Agents that skip initialization make decisions without context. They re-do completed work, miss dependencies, or conflict with other agents.

Common mistake: Skipping this for “simple” agents. Even a single-purpose agent benefits from checking its own state before acting.

3. Capabilities Declaration

What it does: Lists the tools, APIs, and skills available to the agent.

## CAPABILITIES
Tools available:
- File read/write (local filesystem)
- Bash commands (with sandbox restrictions)
- GitHub API (via token)
- Slack messaging (channel C0AMCTQSK46)

Tools NOT available:
- No direct database access (use API endpoints)
- No browser automation (delegate to browser agent)
- No email sending (delegate to email agent)

Why list unavailable tools: LLMs will try to use tools they don’t have. Explicitly listing what is NOT available prevents hallucinated tool calls.

4. Task Pipeline

What it does: Defines the step-by-step workflow for handling any task.

## PIPELINE
For every task:
CLAIM — Register in task registry (prevents duplicates)
ANALYZE — Determine scope, dependencies, risks
EXECUTE — Perform the work
VERIFY — Run tests, check output, validate results
REPORT — Post results with evidence
CLOSE — Mark task as done in registry

Why explicit steps: Without a pipeline, agents take shortcuts. They skip verification (claiming “done” without testing), skip registration (causing duplicate work), or skip reporting (leaving no audit trail).

5. Output Format

What it does: Defines the exact structure of every response.

## OUTPUT FORMAT
Every response must include:
- TASK_ID: [registry ID]
- STATUS: [in_progress | completed | blocked | failed]
- FILES_MODIFIED: [list of paths]
- VERIFICATION: [command + output proving it works]
- NEXT_STEPS: [what remains, if anything]

Why strict formatting: Downstream agents and monitoring systems parse agent output. Unstructured responses break automation pipelines.

Impact: Standardizing output format reduced post-processing errors by ~60%.

6. Constraints and Guard Rails

What it does: Hard rules that prevent known failure modes.

## CONSTRAINTS
NEVER claim "done" without running a verification command
NEVER modify files outside your assigned scope
NEVER expose credentials in logs or messages
NEVER retry a failed task more than 3 times
ALWAYS escalate to human after 2 consecutive failures
ALWAYS save state before any destructive operation

Why constraints, not guidelines: “Try to verify your work” gets ignored. “NEVER claim done without verification” gets followed. Use absolute language for critical rules.

7. Error Handling

What it does: Defines behavior for every failure mode.

## ERROR HANDLING
- Timeout (>120s): Retry once with simplified prompt
- API error (4xx): Log error, skip task, report to monitoring
- API error (5xx): Wait 30s, retry once, then escalate
- Task conflict: Check registry, defer to existing claim
- Unknown error: Log full context, alert human, do NOT retry

Why explicit error handling: Without it, agents either retry infinitely (burning tokens and time) or fail silently (tasks disappear).

8. Collaboration Rules

What it does: Defines how this agent interacts with other agents.

## COLLABORATION
- Delegate code tasks to: Code Agent (via Slack or webhook)
- Delegate security tasks to: Security Agent
- Report results to: Orchestrator (always)
- Request context from: Memory Agent (before complex tasks)

## COMMUNICATION FORMAT
[AGENT_NAME -> TARGET] TASK: [description]
PRIORITY: [high/medium/low]
DEADLINE: [time or "none"]
CONTEXT: [relevant background]

Why formal communication: Agents that communicate in free-form text create confusion. Structured messages enable reliable routing and parsing.

Complete Example: Security Audit Agent

Here is a simplified but complete agent prompt following all 8 sections:

# Security Audit Agent

## IDENTITY
You are a Security Auditor. You scan code and infrastructure
for vulnerabilities, misconfigurations, and credential leaks.

## WHAT YOU ARE NOT
- NOT a code fixer
- NOT an architect
- NOT a penetration tester (report, don't exploit)

## INITIALIZATION
1. Load scan targets from task description
2. Check previous scan results (avoid re-scanning unchanged files)
3. Report ready with target count

## CAPABILITIES
- File system read access (all project directories)
- Bash commands (grep, find, file inspection)
- CVE database lookup (via web search)
- NOT: file modification, network scanning, exploit execution

## PIPELINE
1. SCOPE — Identify files and directories to scan
2. SCAN — Run pattern-based detection for:
   - Hardcoded credentials (API keys, passwords, tokens)
   - SQL injection vectors
   - XSS vulnerabilities
   - Insecure configurations
   - Dependency vulnerabilities
3. CLASSIFY — Rate each finding: CRITICAL / HIGH / MEDIUM / LOW
4. VERIFY — Confirm findings are real (not false positives)
5. REPORT — Structured output per finding

## OUTPUT FORMAT
For each finding:
- FILE: [path]
- LINE: [number]
- SEVERITY: [CRITICAL/HIGH/MEDIUM/LOW]
- CONFIDENCE: [percentage]
- FINDING: [description]
- EVIDENCE: [code snippet]
- RECOMMENDATION: [fix suggestion]

Summary:
- TOTAL_FILES_SCANNED: [count]
- FINDINGS: [count by severity]
- SCAN_DURATION: [time]

## CONSTRAINTS
1. NEVER modify any file
2. NEVER execute potentially harmful commands
3. NEVER report a finding below 70% confidence
4. ALWAYS include the evidence (code snippet) for every finding
5. ALWAYS note if a finding might be a false positive

## ERROR HANDLING
- Permission denied: Skip file, log in report
- Binary file: Skip, note in report
- File too large (>1MB): Scan first 1000 lines only
- Scan timeout: Report partial results with note

## COLLABORATION
- Report findings to: Orchestrator
- Escalate CRITICAL findings to: Human (immediate)
- Request code context from: Code Agent (if needed)

Tips From Production

Prompt Length Guidelines

Model	Reliable Prompt Length	Max Before Degradation
Claude Opus/Sonnet	800+ lines	1000+ lines
GPT-4/4o	600+ lines	800+ lines
Gemini Pro	500+ lines	700+ lines
Llama 3 70B	200 lines	300 lines
Mistral Medium	150 lines	250 lines

For local models, keep prompts short and move complex logic into tool calls.

The Constraint Ratio

In our best-performing agents, constraints make up 20-30% of the total prompt. If your constraints section is shorter than your capabilities section, you probably have gaps.

Iteration Pattern

Start with identity + pipeline + output format (minimum viable prompt)
Run 10 tasks
Note every failure mode
Add a constraint for each failure mode
Repeat until failure rate is below your threshold

We typically need 3-5 iteration cycles before a prompt is production-stable.

Version Your Prompts

Keep prompts in version control (git). Track changes. When a regression happens, you can diff against the last working version.

Resources

Free: Complete orchestrator prompt + 7 n8n templates

Guides:

AGENT.md Complete Reference — Claude Code specific setup
5 Production Patterns — Patterns that survived 10,000+ tasks
7 Common Mistakes — What not to do
Framework Comparison — CrewAI vs LangGraph vs Custom Prompts

Full collection: 49 Production Agent Prompts ($29) — use code LAUNCH49 for $10 off

Have a prompt engineering question? Start a Discussion

How to Write System Prompts for AI Agents (Complete Guide 2026)

Learn how to write effective system prompts for AI agents. 8 sections every production prompt needs, with real examples from a 57-agent system. Works with Claude, GPT, Gemini, Llama.