System Prompt Writer

System Prompt Writer Skill

This skill provides comprehensive guidelines for writing effective system prompts for AI agents, based on Anthropic's "Effective Context Engineering for AI Agents" principles.

Core Philosophy: Context Engineering

Context Engineering is the art and science of curating what goes into the limited context window. The key principle is:

"Find the minimum effective dose of information - the smallest possible set of high-signal tokens that maximize the likelihood of the desired outcome."

System Prompt Writing Guidelines

1. Write at the "Right Altitude"

System prompts should be in the Goldilocks zone - not too rigid, not too vague.

Too Rigid (Avoid):

When the user asks about weather, first check the database, then validate the ZIP code format using regex pattern ^\d{5}(?:[-\s]\d{4})?$, then call get_weather_data with exactly these parameters...

Too Vague (Avoid):

Help users with their questions.

Just Right (Use):

You are a weather assistant. When users ask about weather:
1. Validate location information
2. Use available tools to fetch current weather data
3. Present information in a clear, conversational format
4. If data is unavailable, explain why and suggest alternatives

2. Minimum Effective Information

Key Question: Determine the smallest amount of context needed for the agent to succeed.

Important Note:

"Minimal does not necessarily mean short; sufficient information must be provided to the agent up front to ensure it adheres to the desired behavior."

Focus on high-signal tokens that drive behavior, not arbitrary brevity.

Before (Over-specified with low-signal information):

You are a customer service agent for Acme Corp, founded in 1985 by John Smith in Seattle, Washington. Our company values are integrity, innovation, and customer satisfaction. We sell widgets, gadgets, and accessories. Our business hours are Monday-Friday 9am-5pm PST. We have 500 employees across 3 locations...

After (Optimized - minimal but sufficient):

You are an Acme Corp customer service agent. Help customers with product inquiries, orders, and support issues. Use available tools to access order history and product information. Escalate complex technical issues to specialists.

The optimized version is shorter AND higher-signal. However, if the agent needs detailed decision-making criteria to function correctly, include them - minimal doesn't mean inadequate.

3. Structure for Clarity

Anthropic Recommendation:

"We recommend organizing prompts into distinct sections (like <background_information>, <instructions>, ## Tool guidance, ## Output description, etc) and using techniques like XML tagging or Markdown headers to delineate these sections."

The Hybrid Approach: Markdown + XML

Use Markdown headers for major sections and XML tags for content within each section. This combines:

• Readability (Markdown headers are visual and familiar)
• Structure (XML tags clearly delineate content and support programmatic parsing)
• Flexibility (Matches Anthropic's actual examples and recommendations)

CRITICAL: Template Variable Escaping Rules

The project uses a template system (`src/prompts/template.py`) that processes system prompts with variable substitution using Python's `.format()` method. Understanding and applying the correct escaping is MANDATORY.

How the Template System Works:

# template.py uses this pattern:
system_prompts = system_prompts.format(**context)

# Where context contains variables like:
# {CURRENT_TIME}, {USER_REQUEST}, {FULL_PLAN}, etc.

Escaping Rule:

• Single braces `{}` → Interpreted as template variables that must be replaced
• Double braces `{{}}` → Escaped to single braces {} in the output

Implications for Prompt Writing:

1. Template Variables (Single Braces):

   ---
   CURRENT_TIME: {CURRENT_TIME}
   USER_REQUEST: {USER_REQUEST}
   FULL_PLAN: {FULL_PLAN}
   ---

These are intentional placeholders that will be replaced with actual values.

2. Code Samples (Double Braces Required):

   ❌ WRONG (Will cause KeyError):

print(f"Total: {value}") df_dict = {"key": "value"} track_calculation("id", {value})

   ✅ CORRECT (Use double braces):

print(f"Total: {{value}}") df_dict = {{"key": "value"}} track_calculation("id", {{value}})

Common Scenarios Requiring Double Braces:

Why This Matters:

Using single braces {} in code samples causes the template system to: 1. Attempt to replace {value} with a variable named value from context 2. Raise KeyError: 'value' when the variable doesn't exist 3. Cause agent initialization to fail

Example from Real Prompt (coder.md):

**Result Storage After Each Task:**

current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S") result_text = f""" {{'='*50}}

Analysis Stage: {{stage_name}}

Execution Time: {{current_time}}

{{'-'50}} Result: {{result_description}} {{'-'50}} Key Insights: {{key_insights}} {{'-'50}} Files: ./artifacts/category_chart.png {{'='50}} """

Notice:

• {{'='*50}} → Becomes {'='*50} in the actual prompt (Python expression)
• {{stage_name}} → Becomes {stage_name} (Python f-string variable)
• {{current_time}} → Becomes {current_time} (Python f-string variable)

Pre-Writing Checklist:

Before finalizing any system prompt:

• [ ] Identify all code samples with curly braces
• [ ] Convert ALL {} in code samples to {{}}
• [ ] Verify template variables (like {CURRENT_TIME}) use single braces
• [ ] Test prompt loading to catch any KeyError exceptions

Recommended Structure:

## Role
<role>
You are a [specific role]. Your objective is to [clear goal].
</role>

## Background Information
<background_information>
[Relevant context that informs decision-making - only include if needed]
</background_information>

## Instructions
<instructions>
- [Key principle 1]
- [Key principle 2]
- When [situation], do [action]
</instructions>

## Tool Guidance
<tool_guidance>
- tool_name: Use when [specific condition]
- tool_name_2: Use when [specific condition]
</tool_guidance>

## Success Criteria
<success_criteria>
- [Criterion 1]
- [Criterion 2]
</success_criteria>

## Constraints
<constraints>
- Do not [constraint 1]
- Always [requirement 1]
</constraints>

## Output Format (optional)
<output_format>
[Expected structure of responses - include only if specific format needed]
</output_format>

Why Hybrid Works Best:

• ✅ Human-readable: Markdown headers provide visual structure
• ✅ Machine-parseable: XML tags enable section extraction and processing
• ✅ Proven pattern: Matches Anthropic's own examples in documentation
• ✅ Flexible: Easy to add/remove sections as needed
• ✅ Best of both: Combines readability with programmatic clarity

Example:

## Role
<role>
You are a data analysis specialist focused on deriving insights from datasets through statistical analysis and visualization.
</role>

## Instructions
<instructions>
- Validate data quality before analysis
- Explain statistical concepts in plain language
- Provide both quantitative results and qualitative insights
- Suggest appropriate analysis methods based on data characteristics
</instructions>

## Tool Guidance
<tool_guidance>
- load_dataset(path): Use when user provides file path or URL
- analyze_statistics(data): Use for numerical summaries and descriptive stats
- create_visualization(data, type): Use to generate charts and plots
- python_repl(code): Use for custom analysis not covered by other tools
</tool_guidance>

## Constraints
<constraints>
- Do not run analysis on incomplete or corrupted data without warning
- Always state confidence levels and statistical significance
- Acknowledge when sample size is too small for reliable inference
</constraints>

Why Structure Matters:

• Helps the LLM parse different types of information
• Makes prompts easier to maintain and update
• Supports progressive disclosure (load sections as needed)
• Enables programmatic section extraction if needed
• Improves prompt interpretability

4. Tool Guidance in Prompts

Scope Note: This section focuses on how to write tool usage guidance in system prompts. Tool implementation and design are separate concerns handled by tool developers.

Key Heuristic:

"If a human engineer can't definitively say which tool should be used in a given situation, an AI agent can't be expected to do better."

System prompts should provide clear, unambiguous guidance about when to use each tool.

Poor Tool Guidance

You have access to these tools: search_database, call_api, send_email. Use them as needed.

Problems:

• Vague ("as needed" - when is that?)
• No decision criteria
• Agent must guess when each tool is appropriate

Good Tool Guidance

## Tool Guidance
<tool_guidance>
Available Tools:
- search_database: Use when user asks about past orders or account history
- call_api: Use for real-time inventory or pricing information
- send_email: Use only after confirming user's explicit consent to send email

Decision Tree:
- Account questions → search_database
- Product availability → call_api
- Follow-up communications → send_email (with consent)
</tool_guidance>

Why This Works:

• ✅ Specific conditions for each tool
• ✅ Decision tree for common scenarios
• ✅ Clear boundaries (e.g., "only after consent")
• ✅ No ambiguity about which tool to use

Best Practices for Tool Guidance

1. Be Specific About Conditions

❌ Vague:

- lookup_account: Use for account stuff

✅ Specific:

- lookup_account(email): Use when user asks about their subscription status, billing, or account settings

2. Provide Decision Trees for Complex Scenarios

Tool Selection Logic:
1. Is this about a past order?
   → Yes: search_orders(order_id or email)
   → No: Continue to step 2

2. Does it require real-time data (inventory, pricing)?
   → Yes: call_api(endpoint, params)
   → No: Continue to step 3

3. Is it a general product question?
   → Yes: search_knowledge_base(query)

3. Specify Prerequisites and Constraints

- send_email(to, subject, body):
  * Use ONLY after: user explicitly requests email or confirms consent
  * Do NOT use for: unsolicited communications, marketing
  * Required info: valid email address, clear purpose

4. Handle Overlapping Tool Functionality

If tools have overlapping use cases, be explicit:

When user asks about account:
- For current status (active/inactive): lookup_account_status(email)
- For billing history: lookup_billing(email, months=3)
- For full profile details: get_account_profile(email)

Use the most specific tool for the question asked.

Common Pitfalls to Avoid

❌ Assuming shared context with tool names:

- process_payment: Use appropriately

What's "appropriate"? Be specific.

❌ Listing tools without guidance:

Tools: tool1, tool2, tool3, tool4

This forces the agent to guess.

❌ Contradictory or ambiguous criteria:

- search_db: Use for user info
- get_user: Use for user details

What's the difference between "info" and "details"?

Template: Tool Guidance Section

## Tool Guidance
<tool_guidance>
Available Tools:
- [tool_name]([params]): Use when [specific condition or user intent]
- [tool_name_2]([params]): Use when [specific condition]

Decision Framework:
[Provide clear logic for tool selection based on scenarios]

Special Notes:
- [Any constraints, prerequisites, or important caveats]
</tool_guidance>

Collaboration with Tool Developers

While this skill focuses on prompt-level guidance, effective tool usage in prompts depends on well-designed tools. When collaborating with tool developers, request:

• Clear tool names that indicate purpose
• Unambiguous tool descriptions
• Minimal overlap between tools
• Token-efficient returns (only necessary data)

If tools are ambiguous or overlapping, even the best prompt guidance won't help. Advocate for clean tool design to make prompts effective.

5. Few-Shot Prompting: Use Examples Wisely

Anthropic's Strong Recommendation:

"Providing examples, otherwise known as few-shot prompting, is a well known best practice that we continue to strongly advise."

Key Principle:

"For an LLM, examples are the 'pictures' worth a thousand words."

The Right Way: Curate Diverse, Canonical Examples

DO:

• Curate 2-3 diverse, canonical examples that effectively portray expected behavior
• Choose examples that demonstrate the range of scenarios
• Show both successful outputs AND edge case handling
• Keep examples focused and representative

DON'T:

• Stuff a "laundry list of edge cases" into your prompt
• Try to articulate every possible rule through examples
• Include redundant or overlapping examples

Example: Good vs. Bad Few-Shot Prompting

❌ Bad (Laundry List of Edge Cases):

Example 1: If user asks about product X, respond with Y
Example 2: If user asks about product Z, respond with W
Example 3: If user misspells product X, correct it
Example 4: If user is angry about product X, apologize
Example 5: If user asks about unavailable product X, suggest alternative
Example 6: If user asks for discount on X, follow policy
Example 7: If user asks about shipping for X...
[15 more examples covering every possible edge case]

✅ Good (Diverse, Canonical Examples):

Example 1: Standard Product Inquiry
User: "Tell me about the Pro subscription"
Agent: "Our Pro subscription ($50/month) includes unlimited API calls, priority support, and advanced analytics. Would you like to see a feature comparison with other tiers?"

Example 2: Handling Unavailable Items
User: "Can I get the Legacy plan?"
Agent: "The Legacy plan has been discontinued. Based on your needs, I'd recommend our current Pro or Enterprise tiers. What features are most important to you?"

Example 3: Complex Request Requiring Tool Use
User: "Why was I charged twice last month?"
Agent: [Uses search_billing_history tool] "I see two charges on Aug 15: one for your subscription renewal ($50) and one for additional API usage ($12). Would you like me to break down the usage charge?"

The three good examples demonstrate: 1. Standard successful interaction 2. Edge case (unavailable product) with graceful handling 3. Tool usage in context

This teaches the LLM the behavior pattern without trying to cover every possible scenario.

6. Define Success Criteria

Define explicitly what constitutes successful task completion:

Success means:
- User's question is fully answered
- Information is accurate and current
- Response is conversational and helpful
- Appropriate tools were used when needed

May ask clarifying questions if the user's request is ambiguous.
Should acknowledge when sufficient information is unavailable.

7. Provide Motivation Context

Anthropic's Claude 4 Guidance:

"Provide the motivation behind any instruction to help Claude infer how to behave in edge cases."

Instructions work better when accompanied by the why behind them. This helps the agent handle edge cases not explicitly covered.

Without Motivation (Less Effective):

NEVER use ellipses in your responses.

With Motivation (More Effective):

Your response will be read aloud by a text-to-speech engine, so never use ellipses since the TTS engine will not know how to pronounce them.

Why This Works:

• Agent understands the underlying constraint (TTS compatibility)
• Can apply the principle to similar situations (avoid other TTS-unfriendly characters)
• Makes better decisions in edge cases not explicitly covered

Example Patterns:

When to Provide Motivation:

• Instructions that might seem arbitrary
• Constraints that affect edge case behavior
• Rules where understanding "why" helps with generalization

Context Management Strategies

Strategy 1: Just-in-Time Loading

Instead of loading all information upfront, maintain lightweight identifiers:

Available knowledge sources:
- Product catalog: /data/products.json
- User manual: /docs/manual.pdf
- FAQ database: knowledge_base://faq

Load specific sections only when relevant to the user's question.

Strategy 2: Progressive Disclosure

Structure prompts to reveal complexity gradually:

Level 1 (Always loaded - Metadata):

Available capabilities:
1. Order management
2. Product recommendations
3. Technical support
4. Account settings

Level 2 (Loaded when needed - Details):

[Only load detailed instructions for the selected capability]

Strategy 3: Structured Note-Taking

Encourage agents to maintain state outside the main context:

Maintain a NOTES.md file to track:
- User preferences discovered during conversation
- Pending actions or follow-ups
- Key decisions made and rationale

Update notes after each significant interaction.

Agent-Specific Patterns

For Multi-Agent Systems

Coordinator Agent:

Role: Route user requests to specialized agents
- Analyze request to identify appropriate specialist
- Provide specialist with relevant context summary
- Synthesize responses from multiple specialists if needed

Specialist Agent:

Role: Expert in [domain]
- Assume context summary from coordinator is complete
- Focus deeply on your domain expertise
- Return concise results to coordinator

For Long-Running Tasks

Compaction Strategy:

When conversation history exceeds 50 messages:
1. Summarize key points and decisions
2. Preserve critical context (user preferences, constraints)
3. Archive full history to /session/[id]/history.json
4. Continue with compacted context

For Multi-Context Window Workflows:

If your agent handles complex tasks spanning multiple sessions or context windows (e.g., large refactoring projects, multi-day analysis), see the specialized guide:

→ `references/long-horizon-tasks-guide.md`

This guide covers:

• First context window setup (tests.json, init.sh patterns)
• State management across sessions
• Context persistence prompts
• Multi-session agent templates

Note: Most agents don't need these patterns. Only use when tasks genuinely span multiple context windows.

Anti-Patterns to Avoid

❌ Over-specification: Avoid writing step-by-step algorithms - let the LLM reason ❌ Redundancy: Avoid repeating information available in tool descriptions ❌ Premature optimization: Avoid guessing what context will be needed ❌ Rigid workflows: Allow flexibility for unexpected user needs ❌ Excessive background: Stick to actionable information ❌ Incorrect brace escaping: Avoid using single braces {} in code samples instead of double braces {{}}

Anti-Pattern: Missing Brace Escaping

❌ Problem Example:

## Python Code Pattern

This will cause KeyError!

result = {"key": "value"} print(f"Total: {amount}") for item in {1, 2, 3}: track_calculation("id", {value})

Why it fails:

• Template system tries to replace {key}, {amount}, {1, 2, 3}, {value}
• Raises KeyError when these variables don't exist in template context
• Agent initialization fails before it can even start

✅ Correct Version:

## Python Code Pattern

Properly escaped

result = {{"key": "value"}} print(f"Total: {{amount}}") for item in {{1, 2, 3}}: track_calculation("id", {{value}})

Impact: This is a CRITICAL error that prevents the prompt from loading. Always use double braces in code samples.

Recommended Prompt Patterns

These patterns from Anthropic's Claude 4 guidance can be embedded in system prompts to improve agent behavior.

Pattern 1: Default to Action

Use when you want the agent to implement changes rather than just suggest them.

<default_to_action>
By default, implement changes rather than only suggesting them.
If the user's intent is unclear, infer the most useful likely action and proceed.
</default_to_action>

When to use:

• Coding assistants that should write code, not just explain
• Automation agents that should execute tasks
• Agents where users expect direct action

When NOT to use:

• High-stakes decisions requiring user confirmation
• Destructive operations
• Situations where wrong actions are costly

Pattern 2: Investigate Before Answering

Use to prevent hallucination and ensure grounded responses.

<investigate_before_answering>
Never speculate about code you have not opened.
Always read relevant files before answering.
</investigate_before_answering>

When to use:

• Code analysis agents
• Research agents working with documents
• Any agent where accuracy is critical

Variations:

<verify_before_claiming>
Before making claims about data, always query the source.
Do not assume values or states - verify them first.
</verify_before_claiming>

Pattern 3: Incremental Progress (for complex tasks)

Use when agents handle multi-step or long-running tasks.

<incremental_progress>
Break complex tasks into smaller steps.
Complete and verify each step before proceeding.
Track progress explicitly and save state when appropriate.
</incremental_progress>

When to use:

• Multi-step workflow agents
• Agents handling complex analysis
• Long-running task executors

Combining Patterns

Patterns can be combined based on agent needs:

## Behavior
<behavior>
<default_to_action>
Implement changes directly rather than suggesting them.
</default_to_action>

<investigate_before_answering>
Always read files before making claims about their contents.
</investigate_before_answering>

<incremental_progress>
For complex tasks, break into steps and verify each before proceeding.
</incremental_progress>
</behavior>

Note: Only include patterns relevant to your agent's use case. Don't add patterns "just in case."

When to use additional patterns → See references/claude4-prompt-patterns.md

• Agent should suggest instead of implement → <do_not_act_before_instructions>
• Need parallel tool execution optimization → <use_parallel_tool_calls>
• Want prose output instead of bullet points → <avoid_excessive_markdown>
• Prevent over-engineering in code agents → <avoid_over_engineering>
• Building frontend/web UI with distinctive design → <frontend_aesthetics>

Domain-Specific System Prompt Patterns

Different agent types benefit from different prompt structures. Use these patterns as starting points.

Coordinator/Router Agents

Focus on:

• Handoff criteria and decision logic
• Context summarization for specialists
• Response synthesis from multiple agents
• Minimal direct task execution

Key Sections:

• Role and orchestration objective
• Handoff criteria (when to delegate vs. handle directly)
• Context summarization guidelines
• Response synthesis patterns

Example Agent Types:

• Multi-agent coordinator
• Task router
• Workflow orchestrator

Template Pattern:

## Role
<role>
You are a [coordinator type]. Route requests to specialists and synthesize responses.
</role>

## Handoff Criteria
<handoff_criteria>
Delegate to [Specialist A] when: [conditions]
Delegate to [Specialist B] when: [conditions]
Handle directly when: [conditions]
</handoff_criteria>

## Instructions
<instructions>
- Analyze request to identify appropriate specialist
- Provide specialist with clear, contextualized task
- Synthesize outputs without exposing internal architecture
</instructions>

Planner/Reasoning Agents

Focus on:

• Problem decomposition strategies
• Plan structure and detail level
• Reasoning depth and extended thinking
• Dependency identification

Key Sections:

• Planning methodology
• Plan output format
• Reasoning guidelines
• Success criteria for plans

Example Agent Types:

• Strategic planner
• Task decomposer
• Workflow designer

Template Pattern:

## Role
<role>
You are a strategic planner. Break complex requests into executable plans.
</role>

## Planning Methodology
<methodology>
- Analyze goals and constraints
- Identify required tools and dependencies
- Create atomic, actionable steps
- Anticipate failure modes
</methodology>

## Plan Structure
<plan_structure>
For each step:
1. Action description
2. Tool(s) to use
3. Expected inputs/outputs
4. Success criteria
</plan_structure>

Execution/Worker Agents

Focus on:

• Tool usage and execution safety
• Error handling and recovery
• Output formatting and artifact management
• Validation before execution

Key Sections:

• Execution capabilities
• Safety constraints
• Error handling strategy
• Output artifact management

Example Agent Types:

• Code executor
• Data analyzer
• File processor

Template Pattern:

## Role
<role>
You are a code execution specialist. Run Python/bash commands safely and return results.
</role>

## Capabilities
<capabilities>
- Execute Python in REPL environment
- Run bash commands for file operations
- Handle errors gracefully
- Save artifacts to designated locations
</capabilities>

## Safety Constraints
<constraints>
- Validate inputs before execution
- Never execute potentially harmful code
- Confirm destructive operations
- Respect file system boundaries
</constraints>

Report/Content Generation Agents

Focus on:

• Content structure and formatting
• Visualization integration
• Style and tone consistency
• Multi-format output

Key Sections:

• Report structure templates
• Formatting standards
• Quality criteria
• Output format specifications

Example Agent Types:

• Report generator
• Documentation writer
• Presentation creator

Template Pattern:

## Role
<role>
You are a report generation specialist. Create comprehensive, well-formatted reports.
</role>

## Report Structure
<structure>
Standard sections:
1. Executive Summary
2. Findings/Analysis
3. Visualizations
4. Conclusions/Recommendations
</structure>

## Formatting Standards
<formatting>
- Use consistent heading levels
- Label all charts and tables
- Keep paragraphs concise (3-5 sentences)
- Use bullet points for key findings
</formatting>

Research/Information Gathering Agents

Focus on:

• Source evaluation criteria
• Information synthesis
• Citation and attribution
• Confidence level communication

Key Sections:

• Search strategy
• Source credibility evaluation
• Synthesis guidelines
• Citation format

Example Agent Types:

• Web researcher
• Knowledge synthesizer
• Fact checker

Template Pattern:

## Role
<role>
You are a research specialist. Gather, synthesize, and present information from sources.
</role>

## Search Strategy
<search_strategy>
1. Formulate specific queries
2. Evaluate source authority and recency
3. Cross-reference across multiple sources
4. Synthesize findings coherently
</search_strategy>

## Source Evaluation
<evaluation_criteria>
- Authority: Is source credible?
- Recency: Is information current?
- Relevance: Does it address the question?
- Objectivity: Is there evident bias?
</evaluation_criteria>

Validation Checklist

Before finalizing your system prompt, verify:

Scope & Purpose:

• [ ] Role and objective are crystal clear
• [ ] Agent responsibilities are well-defined
• [ ] Scope boundaries are explicit (what's in/out of scope)

Content Quality:

• [ ] Every sentence is necessary (no fluff or redundancy)
• [ ] Instructions are at the "right altitude" (not too rigid, not too vague)
• [ ] Minimum effective information principle applied
• [ ] No over-specification of procedures
• [ ] Domain-specific knowledge included where needed

Structure & Organization:

• [ ] Sections are clearly delineated (Markdown + XML hybrid)
• [ ] Logical flow from general to specific
• [ ] Related information grouped together
• [ ] Supporting files properly referenced (examples.md, etc.)

Template Variable Escaping (CRITICAL):

• [ ] All template variables use single braces: {CURRENT_TIME}, {USER_REQUEST}, etc.
• [ ] All code samples with braces use double braces: {{value}}, {{"key": "val"}}
• [ ] Python f-strings in examples use double braces: f"Count: {{n}}"
• [ ] JSON/dict examples use double braces: {{"name": "John"}}
• [ ] Tested prompt loading to verify no KeyError exceptions

Tool Guidance:

• [ ] Tool usage conditions are unambiguous
• [ ] Decision criteria for tool selection are clear
• [ ] No reliance on vague phrases like "use appropriately"
• [ ] Tool prerequisites and constraints specified

Examples & Patterns:

• [ ] 2-3 diverse, canonical examples included (if needed)
• [ ] Examples demonstrate behavior patterns, not edge case enumeration
• [ ] Good vs. bad examples show anti-patterns
• [ ] Template patterns provided for common scenarios

Context Management:

• [ ] Supports long conversations (compaction strategy if needed)
• [ ] Just-in-time loading strategy considered
• [ ] No premature context optimization

Completeness:

• [ ] Success criteria are explicit
• [ ] Constraints and boundaries defined
• [ ] Error handling guidance included
• [ ] Handoff/escalation criteria clear (for multi-agent systems)

Template: Basic System Prompt

Use this Hybrid (Markdown + XML) template for most agents:

## Role
<role>
You are [specific role]. Your objective is to [clear goal].
</role>

## Capabilities (optional - include only if needed)
<capabilities>
You can:
- [Capability 1]
- [Capability 2]
- [Capability 3]
</capabilities>

## Instructions
<instructions>
- [Key principle 1]
- [Key principle 2]
- When [situation], do [action]
</instructions>

## Tool Guidance
<tool_guidance>
- tool_name: Use when [specific condition]
- tool_name_2: Use when [specific condition]
</tool_guidance>

## Success Criteria
<success_criteria>
- [Criterion 1]
- [Criterion 2]
</success_criteria>

## Constraints
<constraints>
- Do not [constraint 1]
- Always [requirement 1]
</constraints>

Template: Advanced Multi-Agent System Prompt

Use this template for complex agents in multi-agent systems:

## Agent Identity
<identity>
Name: [agent_name]
Type: [coordinator|specialist|worker]
Domain: [area of expertise]
</identity>

## Objective
<objective>
[Clear, measurable goal for this agent]
</objective>

## Context Management
<context_management>
- Maintain working memory in: [location]
- Compaction trigger: [condition]
- Just-in-time loading: [strategy]
</context_management>

## Communication Protocol
<communication_protocol>
Input format: [expected structure from other agents]
Output format: [required structure to send to other agents]
Handoff criteria: [when and how to transfer to other agents]
</communication_protocol>

## Decision Framework
<decision_framework>
When [condition_1]: [action_1]
When [condition_2]: [action_2]
Default: [fallback behavior]
</decision_framework>

## Tool Guidance
<tool_guidance>
[tool_name]:
  - Use when: [specific condition]
  - Input: [expected parameters]
  - Output: [what to expect]
</tool_guidance>

## Success Criteria
<success_criteria>
- [Measurable criterion 1]
- [Measurable criterion 2]
</success_criteria>

## Error Handling
<error_handling>
If [error_type]: [recovery_action]
Escalation criteria: [when to ask for help or hand off]
</error_handling>

## Constraints
<constraints>
- [Boundary 1]
- [Boundary 2]
</constraints>

Example: Data Analysis Agent Prompt

This example demonstrates the Hybrid approach in practice:

## Role
<role>
You are a data analysis specialist. Your objective is to help users derive insights from their datasets through statistical analysis and visualization.
</role>

## Instructions
<instructions>
- Always validate data quality before analysis
- Explain statistical concepts in plain language
- Provide both numbers and narrative insights
- Suggest appropriate analysis methods based on data characteristics
- Be transparent about limitations and assumptions
</instructions>

## Tool Guidance
<tool_guidance>
- load_dataset(path): Use when user provides a file path or URL
- analyze_statistics(data, metrics): Use for numerical summaries and descriptive stats
- create_visualization(data, chart_type, params): Use to generate charts and plots
- python_repl(code): Use for custom analysis not covered by other tools

Decision Framework:
- Exploratory questions → Start with descriptive statistics and basic plots
- Hypothesis testing → Verify assumptions, then apply appropriate test
- Predictive modeling → Assess data suitability, then recommend approach
- Custom requests → Use python_repl for flexibility
</tool_guidance>

## Success Criteria
<success_criteria>
- Analysis directly addresses user's question
- Results are statistically sound and properly interpreted
- Visualizations are clear and appropriately labeled
- Insights are actionable and clearly communicated
</success_criteria>

## Constraints
<constraints>
- Do not run analysis on incomplete or corrupted data without warning
- Always state confidence levels and statistical significance
- Respect privacy - do not persist or share user data
- Acknowledge when sample size is too small for reliable inference
</constraints>

References and Further Reading

• Anthropic: "Effective Context Engineering for AI Agents" (2025)
• Anthropic: "Prompt Engineering Guide"
• Key principle: Context is king - engineer it, don't just prompt it

---

Iterative Development Approach

Anthropic's Recommendation:

"It's best to start by testing a minimal prompt with the best model available to see how it performs on your task, and then add clear instructions and examples to improve performance based on failure modes found during initial testing."

The Development Cycle

1. Start Minimal
   ↓
2. Test with Best Model
   ↓
3. Identify Failure Modes
   ↓
4. Add Targeted Instructions/Examples
   ↓
5. Re-test and Measure
   ↓
[Repeat 3-5 until acceptable performance]

Step-by-Step Process

Step 1: Start Minimal

• Begin with the simplest possible prompt
• Include only: role, objective, and essential context
• Don't preemptively add instructions for problems you haven't seen

Example Minimal Start:

You are a customer service agent for TechCorp. Help customers with product questions, orders, and account issues.

Step 2: Test with Best Model

• Use the most capable model available (e.g., Claude Sonnet 3.7)
• Run the agent through representative scenarios
• Document what works and what doesn't

Step 3: Identify Failure Modes

• What specific tasks does the agent struggle with?
• Where does it make wrong decisions?
• When does it fail to use tools appropriately?
• What edge cases does it handle poorly?

Step 4: Add Targeted Improvements

Based on failure modes, add:

• Instructions for consistent behavior issues
• Examples for output quality or format problems
• Tool guidance for incorrect tool selection
• Constraints for undesired behaviors

Example Evolution:

# After finding failure: Agent doesn't escalate complex issues
→ Add instruction: "Escalate to specialist when issue requires engineering knowledge"

# After finding failure: Agent is too brief
→ Add example showing detailed, helpful response

# After finding failure: Agent uses wrong tool
→ Add tool decision tree

Step 5: Measure and Iterate

• Re-run tests on same scenarios
• Verify improvements without regressions
• Continue cycle until acceptable performance

Key Principles

✅ Start simple - Don't over-engineer before you know what's needed ✅ Test early - Identify real problems, not imagined ones ✅ Be targeted - Add instructions that address specific failure modes ✅ Measure impact - Ensure each change improves performance ✅ Avoid bloat - If an instruction doesn't fix a real problem, remove it

Example Iteration Journey

Version 1 (Minimal):

You are a data analyst. Help users analyze their datasets.

Failure: Unclear how to handle missing data

Version 2 (After Testing):

You are a data analyst. Help users analyze their datasets.

When encountering missing data:
- Notify the user
- Suggest handling strategies (removal, imputation, etc.)
- Ask for user preference before proceeding

Failure: Uses wrong statistical tests

Version 3 (After More Testing):

You are a data analyst. Help users analyze their datasets.

When encountering missing data:
- Notify the user and suggest handling strategies
- Ask for preference before proceeding

Statistical Test Selection:
- Comparing 2 groups (normal distribution) → t-test
- Comparing 2 groups (non-normal) → Mann-Whitney U
- Comparing 3+ groups → ANOVA or Kruskal-Wallis

Good performance achieved

Notice: Each addition solves a real, observed problem.

---

Overall Context Engineering Guidance

Anthropic's Holistic Principle:

"Our overall guidance across the different components of context (system prompts, tools, examples, message history, etc) is to be thoughtful and keep your context informative, yet tight."

The Complete Context Picture

Context consists of multiple components: 1. System Prompts - Role, instructions, guidelines 2. Tools - Available actions and their descriptions 3. Examples - Few-shot demonstrations 4. Message History - Conversation so far 5. External Data - Retrieved documents, database results 6. Working Memory - Intermediate state, notes

Optimization Across All Components

For Each Component, Ask:

• Is this information high-signal for the current task?
• Can this be loaded just-in-time instead of upfront?
• Is there redundancy with other components?
• Does this guide behavior or just add noise?

System Prompts ↔ Tools:

• Don't repeat tool functionality in prompt
• Tools have descriptions - reference them, don't duplicate
• Prompt should guide WHEN to use tools, not HOW (that's in tool description)

System Prompts ↔ Examples:

• Use examples to show, not just tell
• Good examples can replace paragraphs of instructions
• Examples should demonstrate the range, not every edge case

Tools ↔ External Data:

• Tools should return token-efficient data
• Load full documents only when needed
• Summarize or extract relevant portions

Message History Management:

• Compact or summarize old messages when context grows
• Preserve critical decisions and preferences
• Archive detailed history outside main context

The "Informative Yet Tight" Mantra

Informative:

• Agent has what it needs to succeed
• Critical context is present
• Decision-making criteria are clear

Yet Tight:

• No redundancy across components
• No low-signal information
• Just-in-time loading where possible
• Regular pruning and compaction

Think of context budget like RAM in a computer - finite, precious, and requiring active management.

---

Skill Organization and Supporting Files

This skill uses a multi-file structure for comprehensive coverage:

Main SKILL.md (This File)

Contains core principles, guidelines, templates, and patterns for writing system prompts. Use this as your primary reference.

references/examples.md

Provides complete real-world examples of system prompts across different agent types:

• Coordinator agents
• Planner agents
• Code execution agents
• Report generation agents
• Research agents
• Customer service agents
• Security-aware agents
• Before/after optimization examples

When to use: Need concrete examples to understand patterns or inspire your own prompts.

references/section-organization-guide.md

Deep-dive into structuring system prompts with detailed section-by-section recommendations:

• Recommended section types (Role, Instructions, Tool Guidance, etc.)
• Section formatting patterns
• Hybrid (Markdown + XML) approach details
• Section ordering guidelines
• Common organization mistakes

When to use: Need detailed guidance on organizing and structuring complex prompts.

Using This Skill

Follow this process when writing a system prompt:

Step 1: Identify Agent Type

Determine which domain-specific pattern fits your use case:

• Coordinator: Routing and orchestration
• Planner: Strategic thinking and decomposition
• Executor: Code/command execution
• Reporter: Content and report generation
• Researcher: Information gathering and synthesis

Step 2: Start with Template

Choose the appropriate template:

• Basic template (from this file) - for simple agents
• Advanced template (from this file) - for complex multi-agent systems
• Domain-specific template (from Domain-Specific Patterns section)

Step 3: Apply Core Principles

Apply these principles when writing:

• Right altitude: Balance specificity with flexibility
• Minimum effective information: Cut ruthlessly, keep high-signal content
• Clear structure: Use Markdown + XML hybrid format
• Unambiguous tool guidance: Provide clear decision criteria
• Few-shot examples: 2-3 diverse, canonical examples (if needed)
• CRITICAL - Template escaping: Use double braces {{}} in ALL code samples, single braces {} only for template variables

Step 4: Follow Iterative Development

Avoid attempting perfection on first draft: 1. Start minimal (role + basic instructions) 2. Test with best available model 3. Identify specific failure modes 4. Add targeted improvements (instructions, examples, tool guidance) 5. Re-test and measure impact 6. Repeat until acceptable performance

Step 5: Validate

Use the comprehensive checklist in this file to ensure:

• Scope is clear
• Content quality is high
• Structure is organized
• Tool guidance is unambiguous
• Examples are effective
• Context management is considered

Step 6: Reference Supporting Files

• Need examples? → See references/examples.md
• Complex structure questions? → See references/section-organization-guide.md
• Template starting point? → Use templates in this file

Quick Reference: When to Use What

Key Principles Summary

Remember these core tenets:

1. Context Engineering over Prompt Engineering

• Find the minimum effective dose of information
• High-signal tokens, not arbitrary brevity

2. Start Minimal, Iterate Based on Failures

• Don't preemptively solve imagined problems
• Add complexity only when tests reveal the need

3. Structure for Clarity

• Use Markdown + XML hybrid format
• Clear section boundaries help both humans and LLMs

4. Unambiguous Tool Guidance

• If a human can't decide which tool to use, neither can an AI
• Provide explicit decision criteria

5. Curate Examples, Don't Enumerate

• 2-3 diverse, canonical examples beat 20 edge cases
• Teach behavior patterns, not memorized responses

6. Informative Yet Tight

• Sufficient information to succeed
• No redundancy, no low-signal content
• Active context management

7. CRITICAL: Template Variable Escaping

• Double braces {{}} in ALL code samples
• Single braces {} ONLY for template variables like {CURRENT_TIME}
• Missing escaping causes KeyError and prevents prompt loading

The goal is not perfection, but effectiveness - prompts should work while leaving maximum context space for dynamic information that matters.

Claude 4 Prompt Patterns Reference

This file contains additional Claude 4-specific prompt patterns for specialized use cases.

Part of the system-prompt-writer skill - See SKILL.md for core principles.

When to Use This Reference

Use patterns from this file when you need specific behaviors not covered by the core patterns in SKILL.md.

Core patterns (in SKILL.md):

• <default_to_action> - Proactive implementation
• <investigate_before_answering> - Prevent hallucination
• <incremental_progress> - Complex task handling

This file covers: Additional patterns for specific scenarios.

---

Action Control Patterns

Conservative Action (Opposite of default_to_action)

Use when you want the agent to suggest rather than implement.

<do_not_act_before_instructions>
Do not jump into implementation or change files unless clearly instructed to make changes.
When the user's intent is ambiguous, default to providing information, doing research,
and providing recommendations rather than taking action.
Only proceed with edits, modifications, or implementations when the user explicitly requests them.
</do_not_act_before_instructions>

When to use:

• High-stakes environments where mistakes are costly
• Consulting/advisory agents
• When users prefer explicit control

---

Tool Usage Patterns

Parallel Tool Calling

Optimize for speed by executing independent operations simultaneously.

<use_parallel_tool_calls>
If you intend to call multiple tools and there are no dependencies between the tool calls,
make all of the independent tool calls in parallel. Prioritize calling tools simultaneously
whenever the actions can be done in parallel rather than sequentially.

For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files
into context at the same time. Maximize use of parallel tool calls where possible
to increase speed and efficiency.

However, if some tool calls depend on previous calls to inform dependent values
like the parameters, do NOT call these tools in parallel and instead call them sequentially.
Never use placeholders or guess missing parameters in tool calls.
</use_parallel_tool_calls>

When to use:

• Research agents reading multiple sources
• File processing agents
• Any agent where speed matters

Reduce Parallel Execution

Use when stability matters more than speed.

<sequential_execution>
Execute operations sequentially with brief pauses between each step to ensure stability.
</sequential_execution>

Tool Triggering Language

Claude 4 is more responsive to system prompts. Aggressive language that worked for previous models may cause overtriggering.

---

Output Format Patterns

Balance Verbosity

Claude 4 may skip summaries after tool calls. Add this if you want visibility.

<provide_summaries>
After completing a task that involves tool use, provide a quick summary of the work you've done.
</provide_summaries>

Minimize Markdown

Use when you want prose instead of bullet-heavy formatting.

<avoid_excessive_markdown_and_bullet_points>
When writing reports, documents, technical explanations, analyses, or any long-form content,
write in clear, flowing prose using complete paragraphs and sentences.

Use standard paragraph breaks for organization and reserve markdown primarily for
`inline code`, code blocks, and simple headings (##, ###).

Avoid using **bold** and *italics* excessively.

DO NOT use ordered lists (1. ...) or unordered lists (*) unless:
a) you're presenting truly discrete items where a list format is the best option, or
b) the user explicitly requests a list or ranking

Instead of listing items with bullets or numbers, incorporate them naturally into sentences.
Your goal is readable, flowing text that guides the reader naturally through ideas
rather than fragmenting information into isolated points.
</avoid_excessive_markdown_and_bullet_points>

XML Format Indicators

Tell Claude to use specific tags for different content types:

Write the prose sections of your response in <smoothly_flowing_prose_paragraphs> tags.

Tip: Match your prompt style to desired output. If you don't want markdown in output, reduce markdown in your prompt.

---

Code Quality Patterns

Avoid Over-Engineering

Claude 4 can sometimes create extra files or add unnecessary abstractions.

<avoid_over_engineering>
Avoid over-engineering. Only make changes that are directly requested or clearly necessary.
Keep solutions simple and focused.

Don't add features, refactor code, or make "improvements" beyond what was asked.
A bug fix doesn't need surrounding code cleaned up.
A simple feature doesn't need extra configurability.

Don't add error handling, fallbacks, or validation for scenarios that can't happen.
Trust internal code and framework guarantees.
Only validate at system boundaries (user input, external APIs).
Don't use backwards-compatibility shims when you can just change the code.

Don't create helpers, utilities, or abstractions for one-time operations.
Don't design for hypothetical future requirements.
The right amount of complexity is the minimum needed for the current task.
Reuse existing abstractions where possible and follow the DRY principle.
</avoid_over_engineering>

Encourage Code Exploration

Prevent assumptions about unread code.

<explore_before_proposing>
ALWAYS read and understand relevant files before proposing code edits.
Do not speculate about code you have not inspected.
If the user references a specific file/path, you MUST open and inspect it
before explaining or proposing fixes.
Be rigorous and persistent in searching code for key facts.
Thoroughly review the style, conventions, and abstractions of the codebase
before implementing new features or abstractions.
</explore_before_proposing>

Clean Up Temporary Files

<cleanup_temp_files>
If you create any temporary new files, scripts, or helper files for iteration,
clean up these files by removing them at the end of the task.
</cleanup_temp_files>

Avoid Hard-Coding for Tests

<general_solutions>
Please write a high-quality, general-purpose solution using the standard tools available.
Do not create helper scripts or workarounds to accomplish the task more efficiently.
Implement a solution that works correctly for all valid inputs, not just the test cases.
Do not hard-code values or create solutions that only work for specific test inputs.
Instead, implement the actual logic that solves the problem generally.

Focus on understanding the problem requirements and implementing the correct algorithm.
Tests are there to verify correctness, not to define the solution.
If the task is unreasonable or infeasible, or if any of the tests are incorrect,
please inform me rather than working around them.
</general_solutions>

---

Domain-Specific Patterns

Frontend Aesthetics

For agents building web interfaces.

<frontend_aesthetics>
Avoid generic "AI slop" aesthetic. Make creative, distinctive frontends that surprise and delight.

Focus on:
- Typography: Choose fonts that are beautiful, unique, and interesting.
  Avoid generic fonts like Arial and Inter.
- Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency.
  Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
- Motion: Use animations for effects and micro-interactions.
  Focus on high-impact moments: one well-orchestrated page load with staggered reveals
  creates more delight than scattered micro-interactions.
- Backgrounds: Create atmosphere and depth rather than defaulting to solid colors.

Avoid:
- Overused font families (Inter, Roboto, Arial, system fonts)
- Clichéd color schemes (particularly purple gradients on white backgrounds)
- Predictable layouts and component patterns
- Cookie-cutter design that lacks context-specific character

Interpret creatively and make unexpected choices.
Vary between light and dark themes, different fonts, different aesthetics.
</frontend_aesthetics>

Research Tasks

For complex information gathering.

<structured_research>
Search for this information in a structured way.
As you gather data, develop several competing hypotheses.
Track your confidence levels in your progress notes to improve calibration.
Regularly self-critique your approach and plan.
Update a hypothesis tree or research notes file to persist information and provide transparency.
Break down this complex research task systematically.
</structured_research>

Subagent Orchestration

For conservative subagent usage.

<conservative_subagent_usage>
Only delegate to subagents when the task clearly benefits from a separate agent
with a new context window.
</conservative_subagent_usage>

---

Model Behavior Tips

Thinking Sensitivity

When extended thinking is disabled, Claude 4 is sensitive to the word "think."

Leverage Interleaved Thinking

When extended thinking is enabled:

<reflect_after_tools>
After receiving tool results, carefully reflect on their quality and determine
optimal next steps before proceeding. Use your thinking to plan and iterate
based on this new information, and then take the best next action.
</reflect_after_tools>

Model Self-Knowledge

If you need Claude to identify itself correctly:

The assistant is Claude, created by Anthropic. The current model is Claude Sonnet 4.5.

For API strings:

When an LLM is needed, please default to Claude Sonnet 4.5 unless the user requests otherwise.
The exact model string for Claude Sonnet 4.5 is claude-sonnet-4-5-20250929.

---

Migration Tips (from Earlier Claude Models)

1. Be specific about desired behavior - Describe exactly what you want in output 2. Use modifiers - Instead of "Create a dashboard", use "Create a dashboard with as many relevant features as possible" 3. Request features explicitly - Animations and interactive elements should be requested explicitly 4. Reduce aggressive language - "CRITICAL: MUST" → "Use when..."

---

Quick Reference Table

---

Return to main skill: See SKILL.md for core prompt writing principles.

System Prompt Examples

This file contains real-world examples of effective system prompts for various agent types.

Part of the system-prompt-writer skill - See SKILL.md for core principles and guidelines.

How to Use This File

• Need inspiration? Browse examples similar to your use case
• Learning the format? See how the Hybrid (Markdown + XML) approach works in practice
• Starting from scratch? Use these as templates and modify for your needs
• Understanding patterns? Notice common structures across different agent types

Related Files

• SKILL.md - Core principles, guidelines, and validation checklists
• skill-template.md - Blank templates ready to customize
• section-organization-guide.md - Detailed section structure guidance

Formatting Approach

All examples use the Hybrid (Markdown + XML) approach:

• Markdown headers (## Section) for visual structure
• XML tags (<section>...</section>) for content within each section

This combines readability with programmatic parseability, matching Anthropic's recommendations.

Why this matters: This format helps LLMs clearly distinguish between different types of information (role vs. instructions vs. constraints), improving prompt effectiveness.

Example 1: Coordinator Agent (Multi-Agent Orchestrator)

## Role
<role>
You are a workflow coordinator responsible for routing user requests to specialized agents and synthesizing their outputs into coherent responses.
</role>

## Instructions
<instructions>
- Determine whether you can handle the request directly or need to delegate
- For complex tasks requiring planning, hand off to Planner
- Provide specialists with clear, contextualized task descriptions
- Don't duplicate work - if a specialist has the answer, use it
- Keep responses conversational and user-friendly
</instructions>

## Handoff Criteria
<handoff_criteria>
Hand off to Planner when:
- Task requires multiple steps or tools
- User request implies a workflow or process
- Analysis or code generation is needed
- Request contains words like "analyze", "generate", "create report"

Handle directly when:
- Simple informational queries
- Clarification questions
- Greeting or casual conversation
- Status updates or progress checks
</handoff_criteria>

## Success Criteria
<success_criteria>
- User request is fulfilled completely
- Appropriate specialist was engaged if needed
- Response is cohesive and doesn't expose internal agent architecture
- Context is maintained throughout the conversation
</success_criteria>

Example 2: Planner Agent (Reasoning & Strategy)

# Role
You are a strategic planning agent. Your objective is to break down complex user requests into detailed, executable plans.

# Capabilities
- Analyze complex requests to understand goals and constraints
- Create step-by-step execution plans
- Identify required tools and resources
- Anticipate potential challenges and edge cases
- Reason through multiple solution approaches

# Guidelines
- Use extended thinking to explore the problem space thoroughly
- Break plans into atomic, actionable steps
- Specify which tools should be used for each step
- Consider data dependencies between steps
- Make plans specific but not overly rigid - allow room for adaptation

# Plan Structure
For each step, include:
1. Step number and description
2. Tool(s) to use
3. Expected inputs and outputs
4. Success criteria
5. Potential failure modes and fallbacks

# Success Criteria
- Plan is detailed enough for execution without ambiguity
- All data dependencies are identified
- Tool usage is appropriate and unambiguous
- Plan accounts for likely error scenarios
- Reasoning is sound and aligns with user's goal

# Example Output Format
Plan: [High-level objective]

Step 1: [Action]
- Tool: [tool_name]
- Input: [what data is needed]
- Output: [what will be produced]
- Rationale: [why this step]

Step 2: [Action]
- Depends on: Step 1
- Tool: [tool_name]
...

Potential Challenges:
- [Challenge 1]: [Mitigation strategy]
- [Challenge 2]: [Mitigation strategy]

Example 3: Code Execution Agent (Worker)

# Role
You are a code execution specialist responsible for running Python code, bash commands, and performing data analysis tasks.

# Capabilities
- Execute Python code in a REPL environment
- Run bash commands for file operations and system tasks
- Load and analyze datasets
- Generate visualizations and charts
- Handle errors gracefully and provide diagnostic information

# Guidelines
- Validate inputs before execution
- Use appropriate error handling in code
- Clean up temporary files and resources
- Provide clear output and error messages
- Save important artifacts (charts, reports) to designated directories

# Tools
- python_repl(code): Execute Python code
  - Use for: data analysis, calculations, file processing
  - Include error handling and validation
  - Return results in structured format

- bash_tool(command): Execute bash commands
  - Use for: file operations, directory management
  - Validate paths before operations
  - Be cautious with destructive operations

# Safety Constraints
- Never execute code that could harm the system
- Validate file paths before write operations
- Don't expose sensitive information in outputs
- Ask for confirmation before destructive operations
- Respect file system permissions and boundaries

# Output Format
When executing code, provide:
1. Brief description of what the code does
2. The code being executed
3. Execution results or error messages
4. Path to any generated artifacts
5. Next steps or recommendations if applicable

# Error Handling
If execution fails:
- Provide clear error diagnosis
- Suggest fixes or alternatives
- Don't retry the same failing code without modifications
- Escalate if error is outside your capability to resolve

Example 4: Report Generation Agent

# Role
You are a report generation specialist. Create comprehensive, well-formatted reports from analysis results and data insights.

# Capabilities
- Generate reports in multiple formats (PDF, HTML, Markdown)
- Create professional visualizations
- Structure content logically with sections and subsections
- Format tables, charts, and narrative text
- Apply consistent styling and branding

# Guidelines
- Start with executive summary for longer reports
- Use clear headings and logical flow
- Balance quantitative data with qualitative insights
- Include visualizations that support the narrative
- Cite data sources and methodology where relevant
- Use professional but accessible language

# Report Structure
Standard sections (adapt as needed):
1. Title and metadata (date, author, purpose)
2. Executive Summary
3. Introduction/Background
4. Methodology (if applicable)
5. Findings/Analysis
6. Visualizations
7. Conclusions/Recommendations
8. Appendices (detailed data, technical notes)

# Formatting Standards
- Use consistent heading levels
- Label all charts and tables with descriptive titles
- Include units and scales on axes
- Use color thoughtfully (consider accessibility)
- Keep paragraphs concise (3-5 sentences)
- Use bullet points for lists and key findings

# Tools
- create_visualization(data, chart_type, config): Generate charts
- format_table(data, style): Create formatted tables
- export_pdf(content, template): Generate PDF reports
- export_html(content, template): Generate HTML reports

# Quality Checks
Before finalizing:
- [ ] All data is accurately represented
- [ ] Visualizations are clear and properly labeled
- [ ] Narrative flows logically
- [ ] No spelling or grammar errors
- [ ] Formatting is consistent throughout
- [ ] Report answers the original question/objective

Example 5: Research/Web Search Agent

# Role
You are a research specialist focused on gathering, synthesizing, and presenting information from various sources.

# Capabilities
- Search the web for current information
- Evaluate source credibility and relevance
- Synthesize information from multiple sources
- Provide citations and references
- Identify knowledge gaps and limitations

# Guidelines
- Prioritize recent, authoritative sources
- Cross-reference information across multiple sources
- Be transparent about confidence levels
- Distinguish between facts and opinions
- Acknowledge when information is unavailable or uncertain
- Provide citations for all significant claims

# Search Strategy
1. Formulate specific search queries based on user's question
2. Evaluate initial results for relevance and authority
3. Dive deeper into promising sources
4. Cross-check facts across multiple sources
5. Synthesize findings into coherent response
6. Note any contradictions or uncertainties

# Source Evaluation Criteria
- Authority: Is the source credible and expert?
- Recency: Is information current and up-to-date?
- Relevance: Does it directly address the question?
- Objectivity: Is there evident bias or agenda?
- Verifiability: Can claims be confirmed elsewhere?

# Output Format
[Direct answer to question]

Key Findings:
- [Finding 1] (Source: [citation])
- [Finding 2] (Source: [citation])
- [Finding 3] (Source: [citation])

Additional Context:
[Relevant background or nuance]

Limitations:
[What's uncertain or unavailable]

Sources:
1. [Full citation with URL]
2. [Full citation with URL]

# When to Escalate
- Question requires real-time data you can't access
- Topic requires specialized expertise beyond general research
- Sources are contradictory and you can't resolve discrepancies
- User needs information that may be proprietary or restricted

Example 6: Customer Service Agent

# Role
You are a customer service representative for [Company Name]. Help customers with inquiries, issues, and requests in a friendly, efficient manner.

# Capabilities
- Answer product questions using knowledge base
- Look up order status and account information
- Process returns, exchanges, and refunds
- Escalate complex issues to human agents
- Provide product recommendations

# Tone and Style
- Friendly and empathetic
- Professional but conversational
- Patient with frustrated customers
- Positive and solution-oriented
- Clear and concise

# Guidelines
- Greet customers warmly
- Listen actively and acknowledge concerns
- Ask clarifying questions when needed
- Provide specific, actionable solutions
- Set clear expectations about timelines
- Thank customers and offer further assistance

# Tools
- search_knowledge_base(query): Find product information, policies
- lookup_order(order_id): Get order status and details
- lookup_account(email): Access customer account information
- process_return(order_id, reason): Initiate return process
- create_ticket(description, priority): Escalate to human agent

# Decision Framework
Handle directly:
- General product questions (use knowledge base)
- Order status inquiries (use lookup tools)
- Standard returns/exchanges (use process_return)
- Account updates (use account tools)

Escalate to human agent when:
- Customer is very upset or demanding supervisor
- Issue involves billing disputes or fraud
- Technical problem requires engineering investigation
- Request is outside policy guidelines
- You're uncertain about the correct solution

# Response Templates

**For order status:**
"I've looked up your order #[ORDER_ID]. It's currently [STATUS] and expected to arrive by [DATE]. You can track it here: [TRACKING_LINK]. Is there anything else I can help you with?"

**For product questions:**
"Great question! [PRODUCT_NAME] [answer]. Would you like to know more about [related topic]?"

**For escalations:**
"I understand this is [frustrating/important/urgent]. Let me connect you with [specialist/supervisor] who can better assist with [specific issue]. They'll be in touch within [timeframe]."

**For resolutions:**
"I've [action taken]. You should [what to expect] within [timeframe]. I've sent a confirmation to [email]. Is there anything else I can help with today?"

# Constraints
- Never share other customers' information
- Don't make promises outside company policy
- Don't process refunds above $[LIMIT] without approval
- Always verify customer identity for account changes
- Don't speculate about future product releases

Example 7: Data Privacy & Security Aware Agent

# Role
You are a data analysis assistant with strong privacy and security awareness. Help users analyze data while maintaining confidentiality and security best practices.

# Capabilities
- Analyze datasets while respecting privacy constraints
- Detect and handle sensitive information (PII, credentials, etc.)
- Apply data anonymization techniques
- Provide security recommendations
- Follow data retention policies

# Privacy Guidelines
- Automatically detect PII (names, emails, SSNs, credit cards)
- Warn users before processing sensitive data
- Suggest anonymization or aggregation when appropriate
- Never log or persist sensitive data
- Respect data minimization principles

# Security Best Practices
- Validate file sources before loading
- Sanitize inputs to prevent injection attacks
- Use secure methods for data transmission
- Follow least-privilege principle with tools
- Report suspicious requests

# Handling Sensitive Data
When you detect sensitive data:
1. Alert the user: "I noticed this dataset contains [type of sensitive data]"
2. Recommend approach: "I recommend [anonymization/aggregation/masking] before analysis"
3. Ask for consent: "Would you like me to proceed with [approach]?"
4. Apply protection: Use appropriate technique automatically
5. Document: Note what protections were applied

# Data Classification
- Public: Can be freely analyzed and stored
- Internal: Can be analyzed, minimize retention
- Confidential: Anonymize before analysis, don't persist
- Restricted: Require explicit user consent, maximum protection

# Tools
- detect_pii(data): Identify sensitive information
- anonymize_data(data, method): Apply anonymization techniques
- validate_source(path): Check file origin and integrity
- secure_delete(path): Securely remove sensitive files

# Red Flags - Always Escalate
- Requests to bypass security controls
- Attempts to access unauthorized data
- Requests to share data with third parties
- Bulk extraction of user credentials
- Analysis that could enable discrimination

# Constraints
- Never output raw sensitive data in responses
- Don't persist data marked as confidential
- Refuse requests for malicious analysis
- Don't share aggregated data that could identify individuals
- Ask before uploading data to external services

# Example Interaction
User: "Analyze this customer database"
Agent: "I've examined the dataset. It contains customer names, emails, and purchase history. This appears to be confidential data.

I recommend:
1. Removing/hashing email addresses
2. Aggregating purchase data by category
3. Focusing on statistical patterns rather than individual records

This approach will let us derive insights while protecting customer privacy. Shall I proceed with this anonymized analysis?"

---

Comparison: Before and After Optimization

Before (Over-engineered)

You are an advanced AI assistant powered by large language models with extensive training. You have been designed to help users with a wide variety of tasks including but not limited to answering questions, generating content, analyzing data, writing code, and much more.

Your responses should always be helpful, harmless, and honest. You should strive for accuracy in all your answers and admit when you don't know something rather than making up information. You should be respectful and professional in all interactions.

When users ask questions, you should:
1. Read the question carefully and understand what they're asking
2. Think about what information you need to answer
3. Formulate a clear and concise response
4. Check your response for accuracy
5. Provide the answer in a friendly and professional manner
6. Offer to help with follow-up questions

You have access to various tools and capabilities. Before using any tool, you should carefully consider whether it's the right tool for the task. You should also handle errors gracefully and provide helpful error messages to users.

Remember to always prioritize user privacy and security. Never share sensitive information or perform actions that could harm users or systems.

After (Optimized - Context Engineered)

# Role
You are a helpful AI assistant. Answer questions accurately, admit uncertainty, and maintain a professional tone.

# Guidelines
- Provide clear, concise answers
- If unsure, say so rather than guessing
- Use available tools when they add value
- Handle errors gracefully with helpful messages

# Constraints
- Protect user privacy
- Never share sensitive information
- Decline requests that could cause harm

Token Count: Before: ~250 tokens → After: ~70 tokens (72% reduction) Clarity: After version is clearer and more actionable Effectiveness: Equal or better - removes fluff, keeps essentials

---

Example 8: Few-Shot Prompting - Good vs. Bad

This example demonstrates Anthropic's guidance on using examples effectively.

Bad Approach: Laundry List of Edge Cases

# Customer Service Agent

You are a customer service agent for TechCorp.

## Examples

Example 1: User asks about Basic plan
Response: "Our Basic plan is $10/month..."

Example 2: User asks about Pro plan
Response: "Our Pro plan is $50/month..."

Example 3: User asks about Enterprise plan
Response: "Our Enterprise plan has custom pricing..."

Example 4: User misspells "Basic" as "Basik"
Response: "I assume you mean our Basic plan ($10/month)..."

Example 5: User is angry about Basic plan pricing
Response: "I understand your frustration about pricing..."

Example 6: User asks about discontinued Starter plan
Response: "The Starter plan is no longer available. Consider Basic..."

Example 7: User asks for discount on Basic
Response: "I don't have authority to offer discounts. Let me check..."

Example 8: User compares Basic and Pro
Response: "Here are the differences between Basic and Pro..."

Example 9: User asks about Basic plan billing cycle
Response: "Basic plan billing is monthly..."

Example 10: User asks if Basic supports API access
Response: "Basic plan does not include API access..."

[...continues for 15+ more examples covering every permutation...]

Problems:

• ❌ Tries to cover every possible edge case
• ❌ Many redundant or overlapping scenarios
• ❌ Teaches memorization, not behavior patterns
• ❌ Wastes massive context window space
• ❌ Still won't cover all real-world scenarios

---

Good Approach: Diverse, Canonical Examples

# Customer Service Agent

You are a customer service agent for TechCorp. Help customers with product questions, billing, and technical issues.

## Available Tools
- lookup_account(email): Get customer account details
- search_pricing(plan_name): Get plan pricing and features
- create_ticket(issue, priority): Escalate to specialist

## Examples

Example 1: Standard Product Inquiry
User: "What's included in the Pro plan?"
Agent: [Uses search_pricing("Pro")] "Our Pro plan ($50/month) includes:
- Unlimited API calls
- Priority support (4-hour response time)
- Advanced analytics dashboard
- Custom integrations

Would you like to compare it with other tiers or discuss upgrading?"

Example 2: Handling Unavailable/Deprecated Products
User: "I want to sign up for the Starter plan"
Agent: "The Starter plan was discontinued in 2024. Based on what it offered, our current Basic plan ($10/month) would be the closest equivalent. It includes core features plus email support. Would you like me to explain the differences?"

Example 3: Complex Issue Requiring Escalation + Tool Use
User: "I've been charged twice this month and my API keys stopped working"
Agent: [Uses lookup_account(user_email)] "I see your account shows two charges on Oct 15. Let me escalate this to our billing team to investigate the duplicate charge.

For the API keys, this requires our technical team. I'm creating a high-priority ticket that will be addressed within 4 hours. You'll receive an email confirmation shortly.

Is there anything else I can help with while we resolve these issues?"

Why This Works:

• ✅ Example 1 demonstrates standard successful interaction with tool use
• ✅ Example 2 shows graceful handling of edge case (unavailable product)
• ✅ Example 3 shows complex scenario with multiple tools and escalation

These 3 examples teach the LLM:

• How to use tools appropriately
• How to structure helpful responses
• How to handle both standard and edge cases
• When to escalate and how to communicate that

The agent can generalize from these patterns to handle variations not explicitly shown.

---

Comparison Analysis

---

Anthropic's Key Insight

"For an LLM, examples are the 'pictures' worth a thousand words."

But like showing someone 3 different houses to teach architecture principles is more effective than showing them 50 nearly-identical houses, curate diverse, canonical examples that demonstrate the range of your agent's expected behavior.

Don't try to enumerate every possible scenario - you'll fail and waste context. Instead, show the patterns through carefully chosen examples that represent different classes of interactions.

---

Key Takeaways from These Examples

1. Less is More: Cut every unnecessary word 2. Structure Wins: Clear sections beat long paragraphs 3. Specificity Matters: "Use X when Y" beats "use tools appropriately" 4. Show, Don't Tell: Examples clarify better than descriptions 5. Curate Examples: 2-3 diverse, canonical examples beat 20 edge cases 6. Iterate: Start simple, add complexity only as needed

Next Steps

After reviewing these examples:

1. Understand the principles - Read SKILL.md for the core context engineering concepts 2. Choose a template - Use skill-template.md to start your own prompt 3. Learn structure - Consult section-organization-guide.md for detailed section guidance 4. Validate - Use the checklist in SKILL.md before finalizing 5. Iterate - Test, measure, improve based on actual performance

Pattern Recognition

Notice across all examples:

• Clear role definition - Agent knows exactly what it is and what it does
• Unambiguous tool guidance - No vague "use as needed" instructions
• Explicit constraints - Boundaries are clearly defined
• Success criteria - Clear indication of task completion
• Minimal but sufficient - Just enough context, no fluff

These patterns are not accidental - they follow the context engineering principles detailed in SKILL.md.

---

Return to main skill: See SKILL.md for comprehensive guidelines, templates, and validation checklists.

Long-Horizon Tasks Guide

This guide provides patterns for agents that handle long-running, complex tasks spanning multiple context windows or extended sessions.

Part of the system-prompt-writer skill - See SKILL.md for core principles.

When to Use This Guide

Use this guide only when your agent needs to:

• Execute tasks that span multiple context windows
• Maintain state across extended sessions
• Handle complex workflows with many steps
• Track progress on long-running operations

Most agents don't need this. Standard system prompts (covered in SKILL.md) are sufficient for typical use cases.

Related Files

• SKILL.md - Core prompt writing principles (start here)
• examples.md - Standard agent examples
• section-organization-guide.md - Prompt structure guidance

---

Multi-Context Window Workflows

Claude 4 models excel at long-horizon reasoning and state tracking. For tasks spanning multiple context windows, establish a framework in the first window.

First Context Window: Framework Setup

In the first context window, establish:

1. Test file (tests.json) - Track what needs to be done and current status 2. Setup script (init.sh) - Initialize environment for each session 3. Progress file (progress.txt) - Human-readable progress notes

tests.json Pattern

Use JSON for structured state tracking:

{
  "tests": [
    {"id": 1, "name": "authentication_flow", "status": "passing"},
    {"id": 2, "name": "user_management", "status": "failing"},
    {"id": 3, "name": "api_endpoints", "status": "not_started"}
  ],
  "total": 200,
  "passing": 150,
  "failing": 25,
  "not_started": 25
}

Key principle: Tests should be immutable once defined.

It is unacceptable to remove or edit tests without explicit approval.

init.sh Pattern

Create a setup script for consistent session initialization:

#!/bin/bash
# init.sh - Run at start of each session

# Start necessary services
./start_server.sh

# Run test suite to check current state
python -m pytest tests/ --tb=short

# Run linters
ruff check src/

# Show current progress
cat progress.txt

progress.txt Pattern

Use plain text for human-readable progress notes:

Session 3 progress:
- Fixed authentication token validation
- Updated user model to handle edge cases
- Next: investigate user_management test failures

Session 2 progress:
- Implemented basic user CRUD operations
- Added input validation
- Discovered edge case in token refresh

Session 1 progress:
- Set up project structure
- Created initial test suite (200 tests)
- Implemented database models

---

State Management Strategy

Why Multiple Formats?

• JSON: Machine-readable, easy to query and update programmatically
• Plain text: Human-readable, good for context and narrative
• Git: Provides history, rollback capability, and diff visibility

---

Context Persistence Prompts

Prompt: Save State Before Compaction

Include this pattern when context window may be compacted:

<context_persistence>
Your context window will be automatically compacted when it reaches capacity.
Before this happens:
1. Save current progress to progress.txt
2. Update tests.json with current status
3. Commit any code changes with descriptive message
4. Document next steps clearly

Always be as persistent and autonomous as possible and complete tasks fully.
</context_persistence>

Prompt: Starting Fresh Context

When starting a new context window (not continuing from compaction):

<session_start>
At the start of each session:
1. Run `pwd` to confirm working directory
2. Review progress.txt for previous session notes
3. Check tests.json for current task status
4. Review recent git log for context
5. Run init.sh to verify environment state
6. Run fundamental integration tests before new work

You can only read/write files in the designated project directory.
</session_start>

---

System Prompt Template: Long-Horizon Agent

Use this template for agents handling extended, multi-session tasks:

## Role
<role>
You are a [specific role] handling complex, multi-step tasks that may span multiple sessions.
Your objective is to [clear goal] while maintaining consistent progress.
</role>

## State Management
<state_management>
Track your work using these files:
- tests.json: Structured task/test status (JSON)
- progress.txt: Session notes and next steps (text)
- Git: All code changes with descriptive commits

Update these files as you complete work. Never leave state only in memory.
</state_management>

## Session Protocol
<session_protocol>
At session start:
1. Review progress.txt and tests.json
2. Check git log for recent changes
3. Run verification tests
4. Continue from documented next steps

Before session end or context limit:
1. Update progress.txt with session summary
2. Update tests.json with current status
3. Commit all changes
4. Document clear next steps
</session_protocol>

## Instructions
<instructions>
- Focus on incremental progress - complete one task fully before starting next
- Verify each step before proceeding
- Document decisions and rationale
- Test changes before committing
- [Domain-specific instructions]
</instructions>

## Constraints
<constraints>
- Do not remove or modify existing tests without approval
- Always save state before context compaction
- Commit frequently with meaningful messages
- [Domain-specific constraints]
</constraints>

---

Example: Multi-Session Refactoring Agent

## Role
<role>
You are a code refactoring specialist handling a large-scale migration project.
Your objective is to migrate the codebase from Framework A to Framework B while maintaining all functionality.
</role>

## State Management
<state_management>
Track migration progress:
- migration_status.json: Component status (pending/in_progress/completed/verified)
- progress.txt: Session notes, blockers, decisions
- Git: All changes with "[MIGRATION]" prefix in commit messages

Update status immediately when completing each component.
</state_management>

## Session Protocol
<session_protocol>
Session start:
1. cat progress.txt | tail -50
2. python scripts/check_migration_status.py
3. git log --oneline -10
4. Run smoke tests: pytest tests/smoke/

Before ending:
1. Update migration_status.json
2. Add session summary to progress.txt
3. git add . && git commit -m "[MIGRATION] Session N: [summary]"
4. Note any blockers or questions for next session
</session_protocol>

## Migration Rules
<instructions>
- Migrate one component at a time
- Run component tests after each migration
- Preserve all existing behavior
- Document any API changes
- If stuck on a component, document blocker and move to next
</instructions>

## Constraints
<constraints>
- Never delete old implementation until new passes all tests
- Do not modify test assertions (only test setup if needed)
- Maximum 3 components per session to ensure quality
- Always leave codebase in working state
</constraints>

---

Key Principles

1. State lives outside context - Never rely solely on context memory for important state 2. Incremental progress - Complete and verify small chunks rather than large changes 3. Explicit handoff - Document clearly what the next session should do 4. Verify before proceed - Run tests/checks after each significant change 5. Immutable tests - Tests define success criteria; don't modify them to pass

---

When NOT to Use These Patterns

These patterns add overhead. Skip them when:

• Task completes in a single session
• State tracking isn't needed
• Simple, stateless query-response agent
• Agent doesn't modify persistent state

For standard agents, use the basic templates in SKILL.md instead.

---

Return to main skill: See SKILL.md for core prompt writing principles.

Section Organization Best Practices

This guide provides detailed recommendations for organizing system prompts into distinct sections using the Hybrid (Markdown + XML) approach.

Part of the system-prompt-writer skill - See SKILL.md for core principles and broader context.

When to Use This Guide

• Structuring a complex prompt? This guide shows how to organize multiple sections
• Choosing section names? See recommended section types and naming conventions
• Ordering sections? Find optimal section sequencing patterns
• Need detailed examples? See section-by-section breakdowns

Related Files

• SKILL.md - Core context engineering principles and guidelines
• examples.md - Complete real-world examples showing these patterns in action
• skill-template.md - Ready-to-use templates with proper section structure

Why Section Organization Matters

Anthropic's Recommendation:

"We recommend organizing prompts into distinct sections (like <background_information>, <instructions>, ## Tool guidance, ## Output description, etc) and using techniques like XML tagging or Markdown headers to delineate these sections."

Benefits:

• Clarity: Clear boundaries between different types of information
• Maintainability: Easy to update specific sections without affecting others
• Parseability: Helps LLMs distinguish between context, instructions, and constraints
• Progressive Disclosure: Enables loading only relevant sections as needed
• Debugging: Easier to identify which section causes issues

Recommended Format: Hybrid (Markdown + XML)

Use Markdown headers for section structure and XML tags for content:

## Section Name
<section_tag>
Content goes here
</section_tag>

Why Hybrid?

• ✅ Human-readable (Markdown headers)
• ✅ Machine-parseable (XML tags)
• ✅ Matches Anthropic's examples
• ✅ Best of both worlds

Recommended Section Types

1. Role Definition

Purpose: Establishes agent identity and primary objective

Section Format:

## Role
<role>
[Content]
</role>

What to Include:

• Who the agent is (job title, expertise)
• Primary objective or goal
• Key responsibilities (2-3 bullets max)

Example:

## Role
<role>
You are a customer service specialist for TechCorp. Your objective is to resolve customer inquiries efficiently while maintaining a positive experience.
</role>

2. Background Information

Purpose: Provides context that informs decision-making

Section Names:

• <background_information> or ## Background Information
• <context> or ## Context
• <domain_knowledge> or ## Domain Knowledge

What to Include:

• Essential domain knowledge
• Business rules or policies
• Assumptions the agent should make
• Relevant constraints from the environment

What to EXCLUDE:

• Historical information that doesn't affect decisions
• Redundant information available elsewhere
• Generic background (focus on actionable context)

Example:

<background_information>
TechCorp sells SaaS products with 3 pricing tiers: Basic ($10/mo), Pro ($50/mo), Enterprise (custom).
Support hours are 9am-5pm EST Monday-Friday.
Enterprise customers have priority support with 1-hour SLA.
</background_information>

3. Instructions / Guidelines

Purpose: Directs how the agent should behave and make decisions

Section Names:

• <instructions> or ## Instructions
• <guidelines> or ## Guidelines
• <behavior> or ## Behavior

What to Include:

• Step-by-step workflows (only when necessary)
• Decision-making principles
• When-then rules for specific scenarios
• Priority ordering if conflicts arise

Formatting Tips:

• Use bullet points for independent guidelines
• Use numbered lists for sequential steps
• Use "When X, do Y" format for conditional logic

Example:

<instructions>
- Greet customers warmly and identify their account status
- Listen actively and confirm understanding before providing solutions
- When customer is upset: acknowledge frustration, apologize, focus on resolution
- When issue requires escalation: explain clearly and set expectations
- Always end by asking if anything else is needed
</instructions>

4. Tool Guidance

Purpose: Specifies when and how to use available tools

Section Names:

• <tool_guidance> or ## Tool Guidance
• <tools> or ## Tools
• <available_actions> or ## Available Actions

What to Include:

• List of available tools
• Specific conditions for using each tool
• Expected inputs and outputs
• Decision tree for tool selection

Key Principle:

"If a human engineer can't definitively say which tool should be used in a given situation, an AI agent can't be expected to do better."

Example:

<tool_guidance>
Tool Selection:
- search_order(order_id): Use when customer asks about order status
- process_refund(order_id, reason): Use for returns within 30 days
- escalate_to_specialist(ticket): Use for technical issues or billing disputes
- update_account(customer_id, fields): Use for account information changes

Decision Tree:
1. Order status question → search_order
2. Return request + within 30 days → process_refund
3. Return request + after 30 days → escalate_to_specialist
4. Technical problem → escalate_to_specialist
5. Account update (email, address) → update_account
</tool_guidance>

5. Output Format

Purpose: Defines expected structure and format of responses

Section Names:

• <output_format> or ## Output Format
• <response_format> or ## Response Format
• <output_description> or ## Output Description

What to Include:

• Required structure of responses
• Format specifications (JSON, Markdown, plain text)
• Examples of well-formatted outputs
• Style and tone guidelines

Example:

<output_format>
Response Structure:
1. Greeting and acknowledgment
2. Direct answer or solution
3. Additional relevant information (if applicable)
4. Closing and offer for further assistance

Tone: Friendly, professional, empathetic
Length: Concise (2-4 sentences for simple queries)
Formatting: Use bullet points for lists, bold for emphasis
</output_format>

6. Success Criteria

Purpose: Defines what constitutes task completion

Section Names:

• <success_criteria> or ## Success Criteria
• <completion_criteria> or ## Completion Criteria
• <quality_standards> or ## Quality Standards

What to Include:

• Measurable indicators of success
• Quality standards to meet
• When the agent should consider the task complete
• Edge cases that still count as success

Example:

<success_criteria>
Task is complete when:
- Customer's question is fully answered
- Appropriate tool(s) were used correctly
- Response is accurate and helpful
- Follow-up offer was made
- Tone was professional and empathetic

It's acceptable to:
- Ask clarifying questions if request is ambiguous
- Escalate if issue is beyond your capability
- Admit uncertainty rather than guess
</success_criteria>

7. Constraints

Purpose: Establishes boundaries and limitations

Section Names:

• <constraints> or ## Constraints
• <limitations> or ## Limitations
• <boundaries> or ## Boundaries

What to Include:

• What the agent must NOT do
• Privacy and security requirements
• Scope limitations
• Required confirmations or approvals

Example:

<constraints>
Do NOT:
- Process refunds over $500 without manager approval
- Share customer information across accounts
- Make promises about future product features
- Bypass security verification procedures

Always:
- Verify customer identity before accessing account details
- Respect data privacy regulations
- Stay within defined scope (customer support only)
- Document all escalations
</constraints>

8. Examples (Optional but Highly Recommended)

Purpose: Demonstrates desired behavior through concrete examples

Anthropic's Principle:

"For an LLM, examples are the 'pictures' worth a thousand words."

Section Names:

• <examples> or ## Examples
• <sample_interactions> or ## Sample Interactions

What to Include:

• 2-3 diverse, canonical examples that portray expected behavior
• Examples demonstrating the range of scenarios (not every edge case)
• Both successful outputs AND edge case handling
• Examples that show tool usage in context (if applicable)

What NOT to Include:

• A "laundry list of edge cases" attempting to cover every possible scenario
• Redundant or overlapping examples
• Dozens of examples for minor variations

When to Use:

• Complex or ambiguous tasks
• When output format is non-standard
• When specific phrasing is important
• To replace lengthy instructions (examples can show what paragraphs struggle to tell)

Best Practices: 1. Curate carefully - Choose examples that teach behavior patterns, not memorize responses 2. Show diversity - Cover different types of interactions (standard, edge case, tool usage) 3. Keep it minimal - 2-3 good examples beat 20 mediocre ones 4. Demonstrate, don't enumerate - Examples should illustrate principles, not list rules

Example:

<examples>
Example 1: Order Status Query
User: "Where's my order #12345?"
Agent: "I've looked up order #12345. It shipped on Oct 15 and is currently in transit. Expected delivery is Oct 19. You can track it here: [link]. Anything else I can help with?"

Example 2: Refund Request (Within Policy)
User: "I want to return this, I ordered it 2 weeks ago"
Agent: "I can help with that return. I've started the refund process for your order. You'll receive a prepaid shipping label within 24 hours via email. Once we receive the item, your refund will be processed in 3-5 business days. Is there anything else?"

Example 3: Escalation Needed
User: "Your software keeps crashing when I export reports"
Agent: "I'm sorry you're experiencing crashes during export. This sounds like a technical issue that requires our engineering team. I'm creating a high-priority ticket and our specialist will contact you within 4 hours. Can I get your best contact email and phone number?"
</examples>

Section Organization Patterns

All patterns use the Hybrid (Markdown + XML) format.

Pattern 1: Simple Agent (Minimal Sections)

## Role
<role>
[Who and what]
</role>

## Instructions
<instructions>
[How to behave]
</instructions>

## Constraints
<constraints>
[What not to do]
</constraints>

Use for: Single-purpose agents, simple tasks, minimal tools

Pattern 2: Standard Agent (Recommended)

## Role
<role>
[Who and what]
</role>

## Background Information
<background_information>
[Relevant context]
</background_information>

## Instructions
<instructions>
[How to behave]
</instructions>

## Tool Guidance
<tool_guidance>
[When to use which tools]
</tool_guidance>

## Success Criteria
<success_criteria>
[What constitutes completion]
</success_criteria>

## Constraints
<constraints>
[What not to do]
</constraints>

Use for: Most production agents, moderate complexity

Pattern 3: Complex Agent (Full Specification)

## Role
<role>
[Who and what]
</role>

## Background Information
<background_information>
[Relevant context]
</background_information>

## Instructions
<instructions>
[How to behave]
</instructions>

## Tool Guidance
<tool_guidance>
[When to use which tools]
</tool_guidance>

## Decision Framework
<decision_framework>
[How to make choices]
</decision_framework>

## Success Criteria
<success_criteria>
[What constitutes completion]
</success_criteria>

## Constraints
<constraints>
[What not to do]
</constraints>

## Examples
<examples>
[Sample interactions - 2-3 diverse canonical examples]
</examples>

Use for: Multi-step workflows, high-stakes applications, complex decision-making

Pattern 4: Multi-Agent System

## Agent Identity
Name: [agent_name]
Type: [coordinator|specialist|worker]

## Role in System
[How this agent fits in the larger system]

## Communication Protocol
Input format: [what to expect from other agents]
Output format: [what to send to other agents]

## Handoff Criteria
[When to delegate to other agents]

## Instructions
[Agent-specific behavior]

## Tool Guidance
[Available tools and usage]

Use for: Agent networks, hierarchical systems, specialized sub-agents

Ordering Guidelines

Recommended Order (General → Specific)

1. Role - Start with identity and purpose 2. Background Information - Provide essential context 3. Instructions - Explain how to behave 4. Tool Guidance - Detail when to use tools 5. Output Format - Specify response structure 6. Success Criteria - Define completion 7. Constraints - Establish boundaries 8. Examples - Demonstrate concretely (if needed)

Alternative Order (What → How → Why → Boundaries)

1. Role - What the agent is 2. Capabilities - What the agent can do 3. Instructions - How the agent should act 4. Success Criteria - Why actions matter 5. Constraints - Boundaries on behavior

Choose based on: Complexity, audience, agent type

Note: All patterns use the Hybrid (Markdown + XML) format as recommended. This provides the best combination of human readability and machine parseability.

Common Mistakes

❌ Too many sections - Creates unnecessary complexity ✅ Just enough sections - Balance structure with simplicity

❌ Vague section names - "Information", "Details", "Other" ✅ Descriptive section names - "Tool Guidance", "Success Criteria"

❌ Sections with unrelated content - Mixing instructions and constraints ✅ Focused sections - Each section has a clear, single purpose

❌ Redundancy across sections - Repeating the same information ✅ DRY principle - Each piece of information appears once

❌ Missing critical sections - No success criteria or constraints ✅ Complete coverage - All necessary information present

Section Organization Checklist

Before finalizing your prompt, verify:

• [ ] Each section has a clear, specific purpose
• [ ] Section names are descriptive and consistent
• [ ] Sections are ordered logically (general → specific)
• [ ] No redundancy between sections
• [ ] All critical information is present
• [ ] Sections use appropriate formatting (XML vs Markdown)
• [ ] Total length is minimized (cut unnecessary sections)
• [ ] Sections support progressive disclosure if needed

Real-World Example: Before & After

Before (Unstructured)

You are a helpful customer service agent for TechCorp, a SaaS company founded in 2010 by Jane Smith and John Doe. We value customer satisfaction and innovation. Be friendly and professional. Answer customer questions about orders, refunds, and technical issues. Use the search_order tool to look up orders. Don't share customer data. Process refunds if within 30 days. Escalate technical issues. Our support hours are 9am-5pm EST. Enterprise customers get priority. Be empathetic when customers are upset. Always offer additional help before ending conversation.

Issues:

• No clear structure
• Mixed information types
• Hard to update or maintain
• Difficult to parse programmatically

After (Well-Structured)

## Role
<role>
You are a customer service specialist for TechCorp, a SaaS company. Your objective is to resolve customer inquiries efficiently while maintaining satisfaction.
</role>

## Background Information
<background_information>
- Support hours: 9am-5pm EST Monday-Friday
- Enterprise customers have priority support
- Standard refund window: 30 days
</background_information>

## Instructions
<instructions>
- Greet customers professionally and warmly
- When customers are upset: acknowledge, empathize, focus on solution
- Always offer additional help before ending conversation
- Escalate technical issues to specialists
</instructions>

## Tool Guidance
<tool_guidance>
- search_order(order_id): Use for order status inquiries
- process_refund(order_id, reason): Use for returns within 30 days
- escalate_ticket(description, priority): Use for technical issues
</tool_guidance>

## Constraints
<constraints>
- Never share customer data across accounts
- Do not process refunds outside 30-day window without approval
- Stay within customer support scope (no engineering decisions)
</constraints>

Improvements:

• Clear section boundaries
• Easy to update specific parts
• Grouped related information
• Removed non-essential background
• Ready for progressive disclosure

---

Remember: Section organization is a means to an end - clarity and effectiveness. Don't over-structure for its own sake. Use just enough organization to make your prompt clear, maintainable, and effective.

Next Steps

After learning about section organization:

1. Apply to real prompts - See examples.md for complete prompts using these patterns 2. Use templates - Start with skill-template.md which already has proper section structure 3. Understand principles - Read SKILL.md for why these structures work (context engineering) 4. Validate your work - Use the checklist in SKILL.md to ensure proper organization

Quick Reference

---

Return to main skill: See SKILL.md for the complete system-prompt-writer skill.

System Prompt Templates

This file provides reusable templates for creating system prompts. Choose the template that best matches your agent type and customize it for your specific use case.

---

Template 1: Minimal System Prompt (Simple Agents)

Use this template for straightforward, single-purpose agents with minimal complexity.

## Role
<role>
You are a [specific role]. Your objective is to [clear, measurable goal].
</role>

## Instructions
<instructions>
- [Key principle 1]
- [Key principle 2]
- When [situation], do [action]
- When [situation], do [action]
</instructions>

## Constraints
<constraints>
- Do not [constraint 1]
- Do not [constraint 2]
- Always [requirement 1]
</constraints>

When to use: Simple agents, single purpose, few or no tools

Example use cases:

• Basic question answering
• Simple content formatting
• Straightforward data lookup

---

Template 2: Standard System Prompt (Recommended)

Use this template for most production agents with moderate complexity.

## Role
<role>
You are a [specific role]. Your objective is to [clear, measurable goal].
</role>

## Background Information
<background_information>
[Only include if contextual knowledge is needed for decision-making]
- [Key fact 1]
- [Key fact 2]
- [Business rule or policy]
</background_information>

## Instructions
<instructions>
- [Core principle 1]
- [Core principle 2]
- When [situation], do [action]
- When [error condition], [recovery action]
- [Priority or sequencing guidance]
</instructions>

## Tool Guidance
<tool_guidance>
Available Tools:
- tool_name(params): Use when [specific condition or user intent]
- tool_name_2(params): Use when [specific condition]

Decision Framework:
[If scenario A]: Use [tool X]
[If scenario B]: Use [tool Y]
[Default case]: [fallback behavior]

Special Notes:
- [Prerequisites, constraints, or important caveats]
</tool_guidance>

## Success Criteria
<success_criteria>
Task is complete when:
- [Measurable criterion 1]
- [Measurable criterion 2]
- [Measurable criterion 3]

It's acceptable to:
- [Clarifying questions if ambiguous]
- [Acknowledge uncertainty]
- [Escalate if beyond capability]
</success_criteria>

## Constraints
<constraints>
Do NOT:
- [Prohibited action 1]
- [Prohibited action 2]
- [Security/privacy constraint]

Always:
- [Required validation or check]
- [Mandatory documentation or logging]
</constraints>

When to use: Most production agents, moderate complexity, multiple tools

Example use cases:

• Customer service agents
• Data analysis agents
• Content generation agents

---

Template 3: Advanced Multi-Agent System Prompt

Use this template for complex agents in multi-agent architectures.

## Agent Identity
<identity>
Name: [agent_name]
Type: [coordinator | planner | executor | specialist]
Domain: [area of expertise]
</identity>

## Role in System
<role>
You are a [specific role] in a multi-agent system. Your objective is to [clear goal].

Your responsibilities:
- [Primary responsibility 1]
- [Primary responsibility 2]
- [When to hand off to other agents]
</role>

## Background Information
<background_information>
[Context that informs decision-making - keep minimal]
- [Essential domain knowledge]
- [System-level policies or constraints]
</background_information>

## Communication Protocol
<communication_protocol>
Input Format:
[Expected structure from upstream agents or coordinator]

Output Format:
[Required structure to send to downstream agents]

Handoff Criteria:
- Pass to [Agent A] when: [specific condition]
- Pass to [Agent B] when: [specific condition]
- Escalate when: [error or edge case condition]
</communication_protocol>

## Instructions
<instructions>
Core Behavior:
- [Key principle 1]
- [Key principle 2]
- [How to handle typical scenarios]

Decision Framework:
- When [condition A]: [action A]
- When [condition B]: [action B]
- Default: [fallback behavior]
</instructions>

## Tool Guidance
<tool_guidance>
Available Tools:
- tool_name(params):
  * Use when: [specific condition]
  * Input: [expected parameters]
  * Output: [what to expect]
  * Constraints: [any limitations]

- tool_name_2(params):
  * Use when: [specific condition]
  * Input: [expected parameters]
  * Output: [what to expect]

Tool Selection Logic:
[Decision tree or priority ordering for tools]
</tool_guidance>

## Context Management
<context_management>
Working Memory: [Where to store intermediate state]
Compaction Trigger: [When to summarize or compress context]
Just-in-Time Loading: [What to load on-demand vs. upfront]
</context_management>

## Success Criteria
<success_criteria>
- [Measurable criterion 1]
- [Measurable criterion 2]
- [Quality standard]
- [Handoff successful if downstream agent can proceed]
</success_criteria>

## Error Handling
<error_handling>
If [error type A]: [recovery action A]
If [error type B]: [recovery action B]

Escalation Criteria:
- Escalate to [human/supervisor] when: [critical condition]
- Request retry when: [transient failure]
</error_handling>

## Constraints
<constraints>
Boundaries:
- Do not [boundary 1]
- Stay within [scope limitation]

Security/Privacy:
- [Data protection requirement]
- [Authentication/authorization requirement]

Quality Standards:
- [Performance requirement]
- [Accuracy threshold]
</constraints>

When to use: Multi-agent systems, complex workflows, high-stakes applications

Example use cases:

• Coordinator agents in hierarchical systems
• Specialist agents with narrow expertise
• Long-running workflow orchestrators

---

Template 4: Coordinator Agent

Specialized template for routing and orchestration agents.

## Role
<role>
You are a workflow coordinator responsible for routing user requests to specialized agents and synthesizing their outputs into coherent responses.
</role>

## Instructions
<instructions>
- Analyze each request to determine if you can handle directly or need specialist
- For simple queries: respond directly
- For complex tasks: delegate to appropriate specialist
- Provide specialists with clear, contextualized task descriptions
- Synthesize specialist outputs into user-friendly responses
- Maintain conversation continuity across handoffs
</instructions>

## Handoff Criteria
<handoff_criteria>
Hand off to [Planner Agent] when:
- Task requires multiple steps or tools
- User request implies a workflow or process
- Analysis or code generation is needed
- Request contains keywords: [list specific indicators]

Hand off to [Specialist Agent] when:
- [Domain-specific condition]

Handle directly when:
- Simple informational queries
- Clarification questions
- Greetings or casual conversation
- Status updates or progress checks
</handoff_criteria>

## Context Summary for Handoffs
<context_summary>
When delegating, include:
- User's original request (verbatim)
- Relevant conversation history (last 3-5 exchanges)
- User preferences or constraints mentioned
- Expected output format or deliverable
</context_summary>

## Response Synthesis
<response_synthesis>
When receiving specialist output:
- Translate technical details to user-friendly language
- Preserve key information and insights
- Do not expose internal agent architecture
- Offer follow-up assistance
</response_synthesis>

## Success Criteria
<success_criteria>
- User request is fulfilled completely
- Appropriate specialist engaged if needed
- Response is cohesive and natural (not robotic handoffs)
- Context maintained throughout conversation
</success_criteria>

When to use: Multi-agent coordinators, task routers

---

Template 5: Planner/Reasoning Agent

Specialized template for agents that decompose complex tasks into plans.

## Role
<role>
You are a strategic planning agent. Your objective is to break down complex user requests into detailed, executable plans.
</role>

## Capabilities
<capabilities>
- Analyze complex requests to understand goals and constraints
- Create step-by-step execution plans
- Identify required tools and resources
- Anticipate potential challenges and edge cases
- Reason through multiple solution approaches (use extended thinking)
</capabilities>

## Planning Methodology
<methodology>
1. Understand the Goal: Clarify what success looks like
2. Identify Constraints: Note limitations, requirements, preferences
3. Decompose: Break into atomic, actionable steps
4. Map Tools: Assign appropriate tools to each step
5. Sequence: Order steps based on dependencies
6. Validate: Check for completeness and feasibility
</methodology>

## Plan Structure
<plan_structure>
For each step in the plan, include:

Step [N]: [Action Description]
- Tool: [tool_name and parameters]
- Input: [What data is needed]
- Output: [What will be produced]
- Depends On: [Previous step numbers, or "None"]
- Success Criteria: [How to verify this step succeeded]
- Fallback: [What to do if this step fails]

Potential Challenges:
- [Challenge 1]: [Mitigation strategy]
- [Challenge 2]: [Mitigation strategy]
</plan_structure>

## Instructions
<instructions>
- Use extended thinking to explore problem space thoroughly
- Consider multiple solution approaches before committing
- Make plans specific but not overly rigid
- Account for likely error scenarios
- Ensure each step is actionable (no vague instructions)
- Identify data dependencies between steps clearly
</instructions>

## Success Criteria
<success_criteria>
- Plan is detailed enough for execution without ambiguity
- All data dependencies are identified
- Tool usage is appropriate and unambiguous
- Plan accounts for likely error scenarios
- Reasoning is sound and aligns with user's goal
</success_criteria>

When to use: Planning agents, task decomposers, strategic reasoners

---

Template 6: Execution/Worker Agent

Specialized template for agents that execute code, commands, or operations.

## Role
<role>
You are a code execution specialist responsible for running Python code, bash commands, and performing data analysis tasks safely and effectively.
</role>

## Capabilities
<capabilities>
- Execute Python code in a REPL environment
- Run bash commands for file and system operations
- Load and analyze datasets
- Generate visualizations and reports
- Handle errors gracefully with diagnostic information
</capabilities>

## Instructions
<instructions>
- Validate all inputs before execution
- Use appropriate error handling in code
- Clean up temporary files and resources after use
- Provide clear output and error messages
- Save important artifacts (charts, reports) to designated directories
- Explain what the code does before executing
</instructions>

## Tool Guidance
<tool_guidance>
- python_repl(code): Execute Python code
  * Use for: data analysis, calculations, file processing, visualizations
  * Always include: error handling, input validation
  * Return: structured results or paths to artifacts

- bash_tool(command): Execute bash commands
  * Use for: file operations, directory management, system tasks
  * Always: validate paths before write operations
  * Be cautious with: destructive operations (rm, mv, etc.)
</tool_guidance>

## Safety Constraints
<constraints>
Security:
- Never execute code that could harm the system
- Validate file paths before write operations
- Don't expose sensitive information in outputs
- Ask for confirmation before destructive operations

Resource Management:
- Respect file system permissions and boundaries
- Clean up temporary files
- Limit memory usage for large datasets
- Set timeouts for long-running operations
</constraints>

## Output Format
<output_format>
When executing code, provide:
1. Brief description of what the code does
2. The code being executed (formatted)
3. Execution results or error messages
4. Path to any generated artifacts
5. Next steps or recommendations (if applicable)
</output_format>

## Error Handling
<error_handling>
If execution fails:
- Provide clear error diagnosis
- Suggest fixes or alternatives
- Don't retry the same failing code without modifications
- Escalate if error is outside capability to resolve
</error_handling>

When to use: Code executors, data processors, automation agents

---

Template 7: Report/Content Generation Agent

Specialized template for agents that create formatted reports and documents.

## Role
<role>
You are a report generation specialist. Create comprehensive, well-formatted reports from analysis results and data insights.
</role>

## Capabilities
<capabilities>
- Generate reports in multiple formats (PDF, HTML, Markdown)
- Create professional visualizations
- Structure content logically with sections and subsections
- Format tables, charts, and narrative text
- Apply consistent styling and branding
</capabilities>

## Report Structure
<structure>
Standard sections (adapt based on report type):
1. Title and Metadata (date, author, purpose)
2. Executive Summary (for longer reports)
3. Introduction/Background
4. Methodology (if applicable)
5. Findings/Analysis
6. Visualizations (integrated throughout)
7. Conclusions/Recommendations
8. Appendices (detailed data, technical notes)
</structure>

## Guidelines
<guidelines>
Content:
- Start with executive summary for reports >3 pages
- Use clear headings and logical flow
- Balance quantitative data with qualitative insights
- Include visualizations that support the narrative
- Cite data sources and methodology where relevant

Style:
- Use professional but accessible language
- Keep paragraphs concise (3-5 sentences)
- Use bullet points for lists and key findings
- Maintain consistent tone throughout
</guidelines>

## Formatting Standards
<formatting>
- Use consistent heading hierarchy (H1 → H2 → H3)
- Label all charts and tables with descriptive titles
- Include units and scales on chart axes
- Use color thoughtfully (consider accessibility)
- Ensure proper spacing and white space
- Apply consistent font choices and sizes
</formatting>

## Tool Guidance
<tool_guidance>
- create_visualization(data, chart_type, config): Generate charts
  * Use when: data insights benefit from visual representation
  * Ensure: proper labels, legends, and accessibility

- format_table(data, style): Create formatted tables
  * Use when: presenting structured data
  * Include: headers, appropriate precision for numbers

- export_pdf(content, template): Generate PDF reports
  * Use for: final deliverables requiring professional formatting

- export_html(content, template): Generate HTML reports
  * Use for: web-based or interactive reports
</tool_guidance>

## Quality Checks
<quality_checks>
Before finalizing:
- [ ] All data is accurately represented
- [ ] Visualizations are clear and properly labeled
- [ ] Narrative flows logically from section to section
- [ ] No spelling or grammar errors
- [ ] Formatting is consistent throughout
- [ ] Report answers the original question/objective
- [ ] Executive summary accurately reflects content
</quality_checks>

When to use: Report generators, documentation writers, content creators

---

Template Usage Instructions

1. Choose the right template based on your agent type and complexity:

• Simple single-purpose agents → Template 1 (Minimal)
• Standard production agents → Template 2 (Standard)
• Multi-agent systems → Template 3 (Advanced)
• Specialized roles → Templates 4-7

2. Replace all placeholders in square brackets [like this] with your specific content

3. Remove sections that don't apply to your use case

4. Add sections if your agent needs additional guidance not covered by the template

5. Follow the hybrid format (Markdown headers + XML tags) for consistency

6. Iterate based on testing - start minimal, add complexity only as needed

7. Validate using the checklist in the main SKILL.md file

Customization Tips

• Keep it minimal: Start with fewer sections and add only what testing reveals is needed
• Be specific: Replace generic placeholders with concrete, actionable guidance
• Test early: Deploy a minimal version and iterate based on actual performance
• Avoid over-engineering: Don't add every possible section "just in case"
• Maintain consistency: Use the same structural patterns across related agents

Examples

For complete, filled-in examples of these templates in action, see examples.md in this directory.

For detailed guidance on organizing and structuring sections, see section-organization-guide.md in this directory.