Writing Prompts

Overview

The prompt is the fundamental unit of engineering. Every prompt you create becomes a force multiplier—one well-crafted prompt can generate tens to hundreds of hours of productive work. One bad prompt compounds failure at the same rate.

The Stakeholder Trifecta: You're engineering for three audiences:

1. •You - Must understand the prompt months later
2. •Your Team - Must be able to use and modify it
3. •Your Agents - Must execute it reliably

Core Principle: Consistency beats complexity. Use the same format across all your prompts.

Quick Start

Tell me what task you want to automate:

"Create a prompt that reviews my code changes before commit"

I'll identify the appropriate level (1-7) and produce a ready-to-use prompt with the right sections.

When to Use

Always:

• •Creating reusable agentic prompts
• •Writing system prompts for agents
• •Defining tool/function descriptions
• •Building workflow automation

Trigger signals:

• •"write a prompt", "create a command"
• •"automate this workflow"
• •"make this reusable"
• •Three times marks a pattern → capture it as a prompt

Instructions

• •Start at the lowest level that solves the problem—don't over-engineer
• •Most prompts are Level 2-4; reach for Level 5+ only when needed
• •If the user says "simple" or "quick", stay at Level 1-2
• •Always ask: "Could a teammate understand this in 30 seconds?"
• •Avoid adding sections "just in case"—each section must earn its place

The Seven Levels

Each level builds on the previous. Most work happens at levels 2-4.

For detailed examples, read the appropriate level file:

• •Level 1: High-Level
• •Level 2: Workflow
• •Level 3: Control Flow
• •Level 4: Delegation
• •Level 5: Higher-Order
• •Level 6: Template Meta
• •Level 7: Self-Improving

Composable Sections

Sections are swappable Lego blocks. Use only what you need.

Always include: Title, Purpose, Workflow (levels 2+)

Include when needed:

• •Variables: When inputs change between runs
• •Instructions: When guardrails prevent mistakes
• •Report: When output format matters
• •Examples: When behavior is unclear

The Input → Workflow → Output Pattern

Every prompt follows this three-step structure:

┌─────────────────────────────────────────────────┐
│  INPUT                                          │
│  - Variables (dynamic and static)               │
│  - Context (codebase structure, relevant files) │
├─────────────────────────────────────────────────┤
│  WORKFLOW                                       │
│  - Step-by-step numbered execution              │
│  - Control flow (conditionals, loops)           │
│  - Delegation (spawning sub-agents)             │
├─────────────────────────────────────────────────┤
│  OUTPUT                                         │
│  - Report format                                │
│  - Artifacts created                            │
└─────────────────────────────────────────────────┘

Input and Output are for you and your team—quick understanding. Workflow is the actual work—this is where you dial in the step-by-step play.

System Prompts vs User Prompts

System prompts (agent personality): Use Purpose, Instructions, Examples. Avoid prescriptive workflows.

User prompts (reusable commands): Use full section toolkit. This is 90% of what you'll write.

Workflow

1. •

   Identify the Level

   • •Simple repeat task → Level 1
   • •Sequential steps → Level 2
   • •Conditionals/loops → Level 3
   • •Multiple agents → Level 4
   • •Plan as input → Level 5
   • •Generate prompts → Level 6
   • •Learn over time → Level 7
2. •

   Choose Sections

   • •Start minimal. Add only when needed:
   • •Title + Purpose (always)
   • •Workflow (levels 2+)
   • •Variables (if inputs change)
   • •Report (if output format matters)
   • •Instructions (if guardrails needed)
3. •

   Write the Workflow

   • •Numbered steps with clear action verbs
   • •Reference variables by name
   • •Include control flow where needed
   • •Read the appropriate level file (see links above) for patterns
4. •

   Test and Iterate

   • •Run with representative inputs
   • •Check edge cases
   • •Tighten where output varies
   • •Add examples where behavior is unclear

Report

Deliver the prompt in this format:

---
description: <one-line description>
argument-hint: [<args if any>]
allowed-tools: <if restricting tools>
---

# <Prompt Name>

<Purpose: 1-2 sentences>

## Variables (if needed)
## Instructions (if needed)
## Workflow
## Report (if needed)

State the level used and why. If the prompt could be simpler, say so.

Common Mistakes

• •Over-engineering: Starting at Level 5+ when Level 2 suffices
• •Section bloat: Adding sections "just in case"—each must earn its place
• •Wrong prompt type: Writing workflows for system prompts (use Purpose/Instructions instead)
• •Missing context: Sub-agent prompts that assume shared state (they're stateless)
• •Vague workflows: Steps like "analyze the code" instead of specific actions

Example Session

User: Create a prompt that summarizes my git changes

Response: This is a Level 2 Workflow prompt—sequential steps with structured output.

---
description: Summarize recent git changes
allowed-tools: Bash, Read
---

# Git Summary

Summarize recent git changes for quick review.

## Workflow

1. Run `git status` to identify modified files
2. Run `git diff --stat` for change overview
3. Run `git log --oneline -5` for recent commits
4. Synthesize findings into summary

## Report

Provide:
- Files changed (added/modified/deleted)
- Key changes by area
- Recent commit messages