Prompt Optimizer Skill

This skill helps you analyze, optimize, and improve prompt files for LLM-based agents, with specific support for LangGraph agent architectures.

When to Use This Skill

Use this skill when you need to:

• •Analyze existing .prompt files in backroom_agent/prompts/ or subagent prompt directories
• •Improve prompt clarity, structure, or effectiveness
• •Debug agent behavior by examining and refining prompts
• •Create new prompts following best practices
• •Ensure prompts are properly structured for LangGraph nodes
• •Optimize token usage while maintaining instruction quality
• •Validate prompt consistency across subagents

Optimization Framework

1. Prompt Analysis Checklist

When analyzing a prompt file, evaluate:

Clarity & Structure

• • Clear purpose statement at the beginning
• • Logical section organization with headers
• • Unambiguous instructions (no vague terms)
• • Proper use of formatting (bullets, numbering, code blocks)

Specificity

• • Concrete examples provided where needed
• • Clear input/output format specifications
• • Explicit constraints and boundaries
• • Specific terminology definitions

Completeness

• • All required context provided
• • Edge cases addressed
• • Error handling instructions included
• • Output format fully specified

Efficiency

• • No redundant instructions
• • Concise language without losing clarity
• • Relevant context only (no extraneous information)
• • Optimal length for the task complexity

Agent-Specific (LangGraph)

• • State key references are accurate
• • Node-specific instructions are clear
• • Context passing between nodes is explicit
• • Type expectations match protocol definitions

2. Common Issues to Fix

Vague Instructions

• •❌ "Process the data appropriately"
• •✅ "Extract entity names from the text using Named Entity Recognition, returning a list of strings"

Missing Context

• •❌ "Generate a response"
• •✅ "Generate a response in second-person perspective (you/your), incorporating the player's current location from state['current_location']"

Ambiguous Output Format

• •❌ "Return the results"
• •✅ "Return a JSON object with keys: 'success' (boolean), 'message' (string), 'data' (list of dicts)"

Redundant Information

• •❌ Repeating the same instruction in multiple sections
• •✅ State once clearly, reference if needed later

Over-complicated Structure

• •❌ Deeply nested sections with overlapping content
• •✅ Flat, scannable structure with clear headers

3. Best Practices

Structure Template

# [Primary Goal/Purpose]

## Context
[Brief description of when/how this prompt is used]
[Reference to state keys available]

## Input Format
[Exact specification of expected inputs]

## Task Instructions
1. [Step-by-step numbered instructions]
2. [Each step should be actionable]
3. [Use imperative mood: "Extract", "Generate", "Return"]

## Output Format
[Exact specification with examples]

## Constraints
- [Explicit limitations]
- [What NOT to do]

## Examples
### Example 1: [Scenario]
Input: ...
Output: ...

### Example 2: [Edge Case]
Input: ...
Output: ...

Language Guidelines

• •Use imperative mood: "Extract entities" not "You should extract entities"
• •Be specific: "Return 3-5 suggestions" not "Return some suggestions"
• •Avoid hedge words: "might", "could", "possibly", "maybe"
• •Use consistent terminology: Define terms once, use them consistently
• •Provide examples: Show, don't just tell

State Key References (for LangGraph agents)

When referencing state keys in prompts:

• •Use exact key names from state.py files
• •Include type information: state['player_inventory'] (List[Item])
• •Note if keys might be None/empty: state['active_events'] (List[Event], may be empty)
• •Group references by the node that produces them

4. Optimization Process

Step 1: Understand the Node's Role

• •What is the node's single responsibility?
• •What state does it read?
• •What state does it produce?
• •How does it fit in the graph flow?

Step 2: Analyze Current Prompt

• •Run through the analysis checklist above
• •Identify specific issues using the common issues list
• •Note token count and complexity

Step 3: Draft Improvements

• •Restructure for clarity using the template
• •Simplify language while adding specificity
• •Add missing examples or constraints
• •Remove redundancy

Step 4: Validate

• •Check alignment with state.py definitions
• •Ensure protocol compliance (refer to PROTOCOL.md)
• •Verify examples are accurate
• •Confirm output format matches expected types

Step 5: Document Changes

• •List what was improved and why
• •Note any assumptions or decisions made
• •Suggest related prompts to review for consistency

Working with BackroomAgent Prompts

For the BackroomAgent project specifically:

Directory Structure

backroom_agent/
├── prompts/
│   ├── dm_agent.prompt              # Main DM agent system prompt
│   ├── game_context_to_script.prompt
│   └── init_summary.prompt
└── subagents/
    ├── event/
    │   └── prompts/
    │       ├── analyze.prompt
    │       ├── execute.prompt
    │       └── trigger.prompt
    ├── level/
    │   └── prompts/
    │       ├── analyze.prompt
    │       └── fetch.prompt
    └── suggestion/
        └── prompts/
            ├── analyze.prompt
            └── generate.prompt

Protocol Alignment

Always cross-reference prompts with:

• •PROTOCOL.md - Source of truth for data structures
• •backroom_agent/protocol.py - Pydantic models
• •backroom_agent/state.py - Main agent state
• •backroom_agent/subagents/*/state.py - Subagent states

Consistency Rules

• •All prompts should use consistent terminology from the protocol
• •Item/Entity references should align with the "lists of strings" pattern
• •Event triggers should reference the event schema structure
• •Level data should match the Go agent's output structure

Example Optimization

See example-optimization.md for a detailed before/after example of optimizing a prompt file.

Tips

• •Test prompts: Use scripts/run_*.py to test agent behavior after changes
• •Version control: Keep the original prompt commented out temporarily
• •Incremental changes: Optimize one section at a time and test
• •Context awareness: Consider what the model has already seen before this prompt
• •Token efficiency: Aim for 20-30% reduction without losing clarity
• •Readability: A human should be able to understand the prompt without context

Related Resources

• •PROTOCOL.md - Data structure definitions
• •Subagent README - Subagent architecture
• •LangGraph Documentation - Graph concepts