A good agent prompt is a committed, replayable template — not a chat message — that specifies what to read, what to produce, and what to report back, so the same prompt run twice yields comparably good output both times.

Guide

How to Prompt

Start here

A prompt is a contract — not a conversation opener.

conversation opener

🗣 Ad-hoc chat message

input"fix the login bug"

reads??? whatever it guesses

output??? prose, maybe code

report— unspecified —

replaynot reproducible

Every run is a new experiment. You can't compare outputs, you can't improve the prompt, and you can't catch model drift — because the input never stabilises.

committed contract

📄 Template in .claude/commands/

readsenumerated file list

producesnamed artifact at path

formatexplicit schema

reportbounded summary shape

replaysame input → same output

Run it twice, compare two outputs. The prompt is now an eval. Improve phrasing, measure lift. Swap models, measure drift.

If the prompt lives only in a chat bubble, it cannot be improved — you'd have to remember what you typed and why.

The reading path

Seven nodes. Deepest truth first, most concrete last.

Read top-down on first encounter · skim bottom-up when you just need the shape

01

The Plan is the Prompt

Plan doc and agent prompt are the same artifact. Great planning is great prompting.

governing truth

02

Context Has a Sweet Spot

Too much context degrades; too little misdirects. Aim for the range, not the floor.

calibration

03

Prompts Are Evals

A committed, replayable prompt doubles as a benchmark. Replay across model versions to measure drift.

calibration

04

Plan-as-Prompt

The canonical structure: one artifact, two jobs — plan for humans, prompt for agents.

shape

05

Prompt Template Authoring

The mechanics: Variables / Instructions / Relevant Files / Format / Report — plus a nine-section menu when the minimum isn't enough.

craft

06

Minimum Context

Pass exactly what's needed. No chat history. No background-just-in-case. Every token competes with the task.

craft

07

Command · Plan

.claude/commands/<name>.md is where the template lives. Versioned, improvable, replayable.

on disk

The order matters — craft without the governing truth produces tidy prompts that still drift.

What it looks like on disk

Five sections, minimum. Nine when the task demands it.

.claude/commands/ship-feature.md

committed

varsfeature_slug:<string># injected at run

target_file:<path>

instr# Instructions

Implement {feature_slug} in {target_file}. Follow existing patterns.

files# Relevant Files

- apps/api/routes.py # patterns live here

- apps/api/tests/ # match the existing style

fmt# Format

Edit {target_file}. Add a test. No new files.

rep# Report

<80 words: what you changed, what you tested, any follow-ups.

Five required sections — Variables, Instructions, Relevant Files, Format, Report. No conversation history. No "you are a helpful assistant." The template is replayable because it doesn't depend on who typed it or when.

Nine-section menu exists for harder tasks — add Examples, Constraints, Glossary, Edge Cases as the task warrants. Never pad for completeness.

What you'll have learned

Eight nodes — one claim each.

The Plan is the Prompt

The planning doc and the agent prompt are the same file, serving two readers.

principle

Context Has a Sweet Spot

Context is a U-curve — starving and flooding both degrade output.

principle

Prompts Are Evals

A committed prompt is a regression test for the model.

principle

Plan-as-Prompt

Canonical pattern for the one-artifact-two-jobs shape.

pattern

Prompt Template Authoring

The 5-section minimum and the 9-section extended menu.

pattern

Minimum Context

Pass only what the task needs — every extra token competes.

principle

Command

The on-disk artifact: .claude/commands/<name>.md.

primitive

Plan

When the prompt targets a planner or builder, it's a Plan — with a canonical skeleton.

primitive

When this guide runs out

Two adjacent guides pick up where this one stops.

→ how-to-metaprompt

When one static template isn't enough

Your prompt needs to serve N different contexts at runtime. Covers variable injection and multi-phase composition — turning one template into a family.

→ how-to-author-templates

When you're designing the skeleton

Go up a layer: how do you design the template that a prompt will fill in? For teams building prompt libraries, not one-off commands.

Stay in this guide until your prompts are committed, replayable, and minimum-context. Only then move up the abstraction ladder.

The discipline

If the prompt isn't committed and replayable, it isn't a prompt — it's a message.

Good prompts are templates, not prose. They name what to read, what to produce, and what to report — so two runs are comparable, drift is measurable, and the phrasing is improvable over time.