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):
   ```python
   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:

Context	Wrong	Correct
Python f-strings	f"Count: {n}"	f"Count: {{n}}"
Dictionary literals	{"key": "val"}	{{"key": "val"}}
Set literals	{1, 2, 3}	{{1, 2, 3}}
Format strings	"{:.2f}".format(x)	"{{:.2f}}".format(x)
JSON examples	{"name": "John"}	{{"name": "John"}}
Placeholders in text	Use {variable}	Use {{variable}}

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:**
```python
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:**

```markdown
## 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
• ✅ De

---

Content truncated.