prompt-engineering

# Prompt Engineering Skill

## Overview

This skill covers best practices for writing effective LLM prompts, specifically in the context of prompt-library's template variable system. It documents patterns for structuring prompts, managing context, and versioning for iterative improvement.

## Template Variable Design

### Naming Conventions

Good variable names are descriptive and indicate the content type:

| Pattern | Good | Avoid |
|---------|------|-------|
| Content type | `{{code}}`, `{{document}}`, `{{query}}` | `{{x}}`, `{{input}}` |
| Qualified type | `{{python_code}}`, `{{user_message}}` | `{{stuff}}`, `{{thing}}` |
| Enumerated type | `{{language}}`, `{{style}}`, `{{tone}}` | `{{option}}` |
| Count/quantity | `{{max_length}}`, `{{num_examples}}` | `{{n}}` |

### Variable Placement

Put context-setting variables early, content variables last:

```
Translate the following text from {{source_language}} to {{target_language}}.
Maintain a {{tone}} tone appropriate for a {{audience}} audience.

Text to translate:
{{text}}
```

Good: `source_language`, `target_language`, `tone`, `audience` set context; `text` is the payload at the end.

### Default Values

Set defaults for variables that are frequently the same:

| Variable | Example default |
|----------|----------------|
| `language` | `Python` |
| `tone` | `professional` |
| `format` | `markdown` |
| `max_length` | `500 words` |
| `audience` | `general` |

Never set a default for the primary content variable (the one that changes every run).

## Prompt Structure Patterns

### Instruction + Format + Content

The most reliable structure for most tasks:

```
{{instruction_verb}} the following {{content_type}} and {{output_requirement}}.

{{format_spec}}

{{content}}
```

Example:
```
Summarize the following article and extract the 3 most important takeaways.

Format your response as:
- Summary: (2-3 sentences)
- Key takeaways: (numbered list)

Article:
{{article}}
```

### Role + Task + Context + Content

For specialized tasks requiring domain expertise:

```
You are a {{role}} specializing in {{domain}}.

Your task: {{task_description}}

Context: {{context}}

Input:
{{content}}
```

Note: In prompt-library, the role/persona goes in the **System Message** field, not the prompt body. This makes it easier to reuse the same persona across different task prompts.

### Chain of Thought (CoT)

Append reasoning instructions to improve accuracy on complex tasks:

```
{{question}}

Think step by step before giving your final answer. Show your reasoning.
```

Or with XML tags (works well with Claude):
```
{{question}}

<thinking>
Walk through your reasoning step by step.
</thinking>

<answer>
Your final answer here.
</answer>
```

### Few-Shot Examples

Embed examples directly in the prompt body when output format needs to match exactly:

```
Convert natural language to SQL. Return only the SQL, no explanation.

Examples:
Input: Find all users who signed up in March 2026
Output: SELECT * FROM users WHERE created_at >= '2026-03-01' AND created_at < '2026-04-01';

Input: Count active subscriptions by plan
Output: SELECT plan, COUNT(*) FROM subscriptions WHERE status = 'active' GROUP BY plan;

Input: {{user_query}}
Output:
```

## Output Format Instructions

### Requesting Structured Output

```
Analyze the following code and return your findings as JSON with this structure:
{
  "bugs": [{"line": number, "description": string, "severity": "critical"|"high"|"medium"|"low"}],
  "suggestions": [{"description": string, "impact": "high"|"medium"|"low"}],
  "overall_quality": "good"|"fair"|"poor"
}

Return only the JSON, no markdown fences, no explanation.

Code:
{{code}}
```

### Length Control

```
{{task}}

Keep your response to {{max_words}} words or fewer. Be concise and direct.
```

Or use a soft constraint:
```
{{task}}

Provide a complete answer. Aim for approximately {{target_length}}.
```

## Version Strategy

### When to Create a New Version

Create a new version when:
- Changing the prompt structure or instructions
- Adding or removing variables
- Adjusting output format requirements
- Adding few-shot examples
- Fixing incorrect behavior

Do not create a new version for:
- Changing variable values at run time (that is just a new run)
- Cosmetic whitespace changes with no semantic effect

### Commit Messages

Good commit messages describe what changed and why:

| Good | Avoid |
|------|-------|
| `add output format instructions for JSON` | `update` |
| `add chain-of-thought instruction -- improves reasoning` | `fix` |
| `add security review section` | `v2` |
| `tighten length constraint to 300 words` | `change` |

### Comparing Versions

When comparing two versions in the diff view, look for:
1. Lines added: do they add useful context or constraints?
2. Lines removed: is the removed content redundant or harmful?
3. Reordering: does the new order improve logical flow?

Run both versions on the same input to compare outputs before promoting the new version as current.

## System Message Best Practices

System messages in prompt-library are stored per prompt version and sent to the provider as the system role.

Use system messages for:
- Persistent persona/role: `You are an expert Python developer...`
- Behavioral constraints: `Always respond in the user's language.`
- Output style rules: `Never use bullet points. Write in prose.`
- Safety rules: `Do not suggest deleting production data.`

Do not put task-specific instructions in the system message; those belong in the prompt body.

## Handling Long Inputs

For prompts that accept large inputs (code, documents, logs):
- Always put the long input variable **last** in the prompt body.
- Prefix with a label: `Document:\n{{document}}` rather than just `{{document}}`.
- Add a delimiter for clarity: `---\n{{document}}\n---`.

Example:
```
Identify the top 3 action items from the following meeting notes.
Format as a numbered list. Be concise.

Meeting notes:
---
{{notes}}
---
```

## Iterating on Prompts

A reliable iteration loop:

1. Write initial prompt, save as v1.
2. Run on 5-10 representative inputs. Note failures.
3. Identify the most common failure mode.
4. Edit the prompt to address that failure. Save as v2.
5. Run the same inputs on v2. Check that the failure is fixed and no regressions.
6. Repeat from step 3 for the next failure mode.

Use the diff view in prompt-library to see exactly what changed between versions.

## Token Efficiency

Each token costs money (for cloud providers) and consumes context window. Tips:

- Remove redundant instructions: if the model follows an instruction without explicit repetition, remove the repetition.
- Use concise phrasing: "List 3 items" instead of "Please provide a list of 3 items".
- Avoid filler phrases: remove "Certainly!", "Of course!", "Sure!" by instructing the model not to use them in the system message.
- Move examples to a separate few-shot prompt and chain calls if the main prompt becomes very long.

To estimate token count for a prompt, use the token-counter project (`project 69`) or the provider's tokenizer.

## Common Anti-Patterns

| Anti-pattern | Problem | Fix |
|--------------|---------|-----|
| `Be as helpful as possible` | Too vague, no constraints | Specify exactly what helpful means |
| Negatives only: `Don't use jargon` | Models respond better to positives | `Use plain language accessible to non-experts` |
| Vague format: `Return a list` | Ambiguous structure | `Return a JSON array of strings` |
| Too many instructions | Model may miss or deprioritize some | Break into 2-3 focused prompts |
| `Do X and also Y and also Z` | Serial tasks lose focus | One primary objective per prompt |
| Hardcoded values in prompt body | Makes prompt non-reusable | Use `{{variable}}` for anything that changes |