Prompt Engineering

---
name: prompt-engineering
description: Write prompts and agent skills that actually work
author: mager
version: 1.0.0
---

# Prompt Engineering

I build agent skills for a living. I've written system prompts that run 24/7, SOUL.md files that define entire personalities, and SKILL.md files that teach agents new capabilities. Here's what I've learned about writing instructions that AI actually follows.

## Core Principle: Clarity > Cleverness

The best prompts are boring. They're clear, specific, and structured. The AI doesn't need poetry — it needs unambiguous instructions.

## Anatomy of a Good Prompt

### 1. Role (Who Are You?)
Tell the AI what it is. Be specific.

- ❌ "You are a helpful assistant"
- ✅ "You are a senior frontend engineer who specializes in SvelteKit and writes clean, accessible code"

The more specific the role, the better the output. Give it expertise, opinions, and constraints.

### 2. Context (What's the Situation?)
What does the AI need to know to do its job?

- What project is this for?
- What's already been decided?
- What are the constraints?
- Who's the audience?

### 3. Task (What Do You Want?)
One clear action. Not three. Not "and also."

- ❌ "Write a blog post about React hooks and also explain useState and also compare it to class components and make it funny"
- ✅ "Write a 500-word blog post explaining useState to someone who knows JavaScript but is new to React"

### 4. Format (How Should It Look?)
Tell it exactly what shape the output should take.

- "Return JSON with keys: title, description, tags"
- "Use markdown with H2 headers for each section"
- "Bullet points, no paragraphs"
- "Code only, no explanation"

### 5. Examples (Show, Don't Tell)
One example is worth 100 words of instruction.

```
Good commit message: "feat(auth): add GitHub OAuth login flow"
Bad commit message: "updated stuff"
```

## Writing Agent Skills (SKILL.md)

A skill is a prompt that teaches an AI how to do something specific. Structure:

### Frontmatter
```yaml
---
name: skill-name
description: One line that explains what this teaches
author: your-username
version: 1.0.0
---
```

### Content Structure
1. **What this skill does** — one paragraph
2. **How to use it** — what the user says to activate it
3. **The knowledge** — the actual expertise (tables, rules, examples)
4. **Agent behavior** — how the AI should act when using this skill

### The Agent Behavior Section Is Everything
This is where most skills fail. You need to tell the AI:
- What tone to use
- When to ask questions vs. just do it
- What to prioritize
- How to handle edge cases
- When to push back on the user

## System Prompts (SOUL.md)

A SOUL.md defines who an agent IS, not what it does.

**Include:**
- Personality traits and communication style
- Opinions and preferences (have them!)
- Boundaries (what it won't do)
- How it handles uncertainty
- Relationship to the user

**Avoid:**
- Generic "I'm helpful and friendly" (every AI is)
- Lists of capabilities (that's what skills are for)
- Overly long instructions (if it's over 2 pages, you're micromanaging)

## Common Mistakes

### Being Too Vague
"Make it good" → good how? Fast? Pretty? Correct? Funny? Specify.

### Being Too Rigid
"Always respond in exactly 3 bullet points" → sometimes 4 is better. Give guidelines, not straitjackets.

### Not Testing Edge Cases
Your prompt works for the happy path. What happens when:
- The user gives bad input?
- The user asks something adjacent but not exactly what you designed for?
- The user pushes back on the AI's response?

### Forgetting the Human
Prompts serve people. If the output is technically correct but hard to use, the prompt failed.

## Agent Behavior

- Help users write and refine prompts iteratively
- Show before/after examples of prompt improvements
- Test prompts by role-playing the AI receiving them
- Focus on structure and clarity over tricks
- When a user's prompt is vague, ask "what specifically do you want to be different about the output?"
- Teach the SKILL.md format for anyone who wants to share their knowledge