prompt-engineering

What this skill does

# Prompt Engineering: Structured System Prompts for Production Agents

## Core Principles

Effective system prompts are the foundation of reliable AI agents. Well-engineered prompts provide clear role definition, structured instructions, and concrete examples, while maintaining token efficiency and clarity.

**Mandatory Standard**: All Vibekit agents MUST use XML tags to section system prompts for improved model comprehension.

## XML Tag Structure (Required Pattern)

### Standard XML Sections

```xml
<role>
You are a senior software architect specializing in Python development.
Your expertise includes system design, API architecture, and database modeling.
</role>

<instructions>
When analyzing a technical requirement:
1. Read the complete specification
2. Identify core components and their relationships
3. Propose a modular architecture
4. Document key decisions with rationale
5. Highlight potential risks and mitigations
</instructions>

<tools>
You have access to the following tools:
- file_reader: Read source code files
- code_analyzer: Analyze code quality and patterns
- diagram_generator: Create architecture diagrams

Use tools when:
- You need to examine existing code
- Analysis requires data you don't have
- Visual representation would clarify the design
</tools>

<output_format>
Provide your response in this format:

**Analysis Summary**
[Brief overview of the system]

**Architecture Proposal**
[Detailed architecture description]

**Key Decisions**
1. [Decision]: [Rationale]

**Risks & Mitigations**
[Identified risks with mitigation strategies]
</output_format>

<examples>
Example 1: API Design Request
User: "Design a REST API for user management"
Assistant: [Shows complete structured response]

Example 2: Database Schema Design
User: "Create a schema for an e-commerce platform"
Assistant: [Shows complete structured response]
</examples>

<constraints>
- ALWAYS validate input before processing
- NEVER expose sensitive information in responses
- MUST follow the established architectural patterns
- DO NOT make assumptions about undocumented requirements
</constraints>
```

### Why XML Tags?

**Benefits**:
1. **Model Comprehension**: Large language models parse XML structure effectively, understanding section boundaries
2. **Maintainability**: Sections can be updated independently without affecting others
3. **Clarity**: Clear visual separation of different prompt components
4. **Composability**: Sections can be conditionally included or reused across prompts

**Anthropic Research**: Claude models specifically benefit from XML-tagged prompts, showing improved adherence to instructions within tagged sections.

## Role Definition (Opening Section)

### Effective Role Patterns

```xml
<role>
You are [SPECIFIC TITLE] with [X] years of experience in [DOMAIN].

Your core competencies:
- [Competency 1]: [Brief description]
- [Competency 2]: [Brief description]
- [Competency 3]: [Brief description]

Your working style:
- You ask clarifying questions before making assumptions
- You provide step-by-step reasoning for complex decisions
- You cite sources and acknowledge uncertainty when appropriate
</role>
```

**Best Practices**:
- Be specific (not "helpful assistant" but "senior DevOps engineer")
- Include relevant experience areas
- Define behavioral expectations (how agent should work)
- Establish communication style

**Anti-Pattern**:
```xml
<!-- BAD: Vague and generic -->
<role>
You are a helpful AI assistant that answers questions.
</role>

<!-- GOOD: Specific and detailed -->
<role>
You are a principal software engineer specializing in distributed systems
and microservices architecture. You have 10+ years designing large-scale
systems at companies like Google and Netflix.

Your strengths:
- Trade-off analysis for architectural decisions
- Performance optimization and scalability planning
- Clear communication of complex technical concepts
</role>
```

## Instruction Structure (Core Logic)

### Hierarchical Instructions

```xml
<instructions>
## Primary Objective
[One-sentence goal statement]

## When you receive a request:

### Phase 1: Analysis
1. Read all provided context and requirements
2. Identify ambiguities and ask clarifying questions
3. List assumptions you're making
4. Note any missing information needed

### Phase 2: Planning
1. Break down the problem into logical components
2. Identify dependencies between components
3. Propose a high-level approach
4. Present the plan for user approval

### Phase 3: Execution (only after approval)
1. Implement the solution step-by-step
2. Document each decision with rationale
3. Run validation checks
4. Summarize what was accomplished

## Decision-Making Framework
When choosing between options:
- Evaluate technical feasibility
- Consider maintainability and scalability
- Assess security and performance implications
- Document trade-offs clearly
</instructions>
```

**Best Practices**:
- Use hierarchical headings (##, ###) for organization
- Number sequential steps
- Define decision criteria explicitly
- Separate analysis from execution
- Include validation checkpoints

**Anti-Pattern**:
```xml
<!-- BAD: Unstructured wall of text -->
<instructions>
You should analyze the code and find bugs and suggest fixes and make sure
the code is good and follows best practices and has tests and...
</instructions>

<!-- GOOD: Clear, structured steps -->
<instructions>
## Code Review Process

1. **Syntax & Style**
   - Check for linting errors
   - Verify formatting compliance
   - Review naming conventions

2. **Logic & Correctness**
   - Trace execution paths
   - Identify edge cases
   - Check error handling

3. **Testing**
   - Verify test coverage (minimum 80%)
   - Review test quality
   - Suggest missing test cases
</instructions>
```

## Few-Shot Examples (Critical for Reliability)

### Effective Few-Shot Pattern

```xml
<examples>
## Example 1: Simple Query
<user_input>
What's the best way to handle authentication in a REST API?
</user_input>

<assistant_response>
**Analysis**
You're asking about authentication strategies for REST APIs. This is a
foundational security decision that affects the entire system.

**Recommended Approach: JWT with Refresh Tokens**

Rationale:
- Stateless authentication (no server-side session storage)
- Scalable across multiple servers
- Includes expiration for security
- Refresh token pattern prevents constant re-login

**Implementation Pattern**
1. User login returns access token (short-lived, 15 min) + refresh token (long-lived, 7 days)
2. Access token sent in Authorization header: `Bearer <token>`
3. When access token expires, use refresh token to get new access token
4. Refresh tokens stored securely (HTTP-only cookies or secure storage)

**Security Considerations**
- Use HTTPS only
- Implement token rotation
- Add rate limiting on auth endpoints
- Consider multi-factor authentication

**Code Example**
[Provides actual code implementation]
</assistant_response>

## Example 2: Complex Design Task
<user_input>
Design a data pipeline for processing 1M events per second.
</user_input>

<assistant_response>
**Clarifying Questions (Always Ask First)**
1. What's the event payload size?
2. What processing is required (filtering, enrichment, aggregation)?
3. What's the acceptable latency?
4. What's the retention period for raw data?
5. What's the budget constraint?

[Assuming answers provided...]

**Architecture Proposal**
[Shows complete structured response with diagrams]
</assistant_response>

## Example 3: Error Handling
<user_input>
How should I handle errors in async Python code?
</user_input>

<assistant_response>
[Shows structured response with code examples and anti-patterns]
</assistant_response>
</examples>
```

**Why Few-Shot Works**:
- Demonstrates expected response format
- Shows reasoning process
- Establishes quality bar
- Reduces ambiguity

**Guidelines**:
- Include 3-5 diverse examples
- Show edge cases (not just happy path)
- Demonstrate clarifying questions
- Inc