ysskrishna logoysskrishna

Chapter 1 of 8 · 3 min

The anatomy of an actionable prompt

Goal, context, constraints, output and a done-when check: five parts that turn a vague request into work an agent can finish.

Most bad agent results start with a prompt that describes a wish instead of a task. "Make the checkout faster" is a wish. The agent has to guess what faster means, where to look, what it may change and when to stop. Every guess is a chance to go wrong.

An actionable prompt removes the guesses. It has five parts.

The five parts

PartQuestion it answersExample
GoalWhat outcome do you want?"Cut p95 latency of POST /checkout below 300 ms."
ContextWhat does the agent need to know that it cannot see?"Profiling shows 70% of time in price_cart(). Prices change daily."
ConstraintsWhat must it do or avoid?"No new dependencies. Keep the public API unchanged."
OutputWhat should it hand back?"A diff plus a 5-line explanation."
Done whenHow will you both know it worked?"pytest tests/checkout passes and the benchmark script shows < 300 ms."

You will not need all five every time. A one-line fix needs a goal and maybe a done-when. But when a result disappoints, the missing part is usually one of these.

Before and after

Before:

Make the checkout faster.

After:

Goal: cut p95 latency of POST /checkout below 300 ms (currently ~800 ms).
Context: profiling (attached) shows ~70% of time in price_cart() in
src/billing/pricing.py. Prices change once a day.
Constraints: no new dependencies; keep the function signatures; do not
touch the payment client.
Output: a diff and a short explanation of the change and its risks.
Done when: pytest tests/checkout passes and scripts/bench_checkout.py
reports p95 < 300 ms.

The second prompt is longer, but it saves the agent from reading the whole billing package, stops it adding Redis "to be safe", and gives it a way to check its own work.

Write the goal as an outcome

Compare:

  • "Refactor the auth module." (activity)
  • "Make it possible to add a new OAuth provider by adding one file." (outcome)

The outcome tells the agent which refactor you want, and gives you a test: can you add a provider with one file?

Done-when is the most underused part

Agents that can run commands can check themselves, if you tell them how. A done-when line turns "I think this works" into "I ran the tests and they pass".

Good done-when checks are:

  • Runnable: a command, a script, a URL to load.
  • Specific: "returns 200 with a JSON body containing id", not "works".
  • Cheap: seconds, not an hour-long suite, so the agent actually runs them.

Step by step: rewrite one of your prompts

  1. Open your last three agent chats and pick the one that needed the most follow-ups.
  2. Copy your first message into a scratch file.
  3. Under it, write the five headings: Goal, Context, Constraints, Output, Done when.
  4. Fill each heading using what you had to explain in the follow-ups.
  5. Next time a similar task comes up, start with the filled version and count the follow-ups again.

Common mistakes

  • Hiding the goal in the middle. Put it first. Models weigh the start of a message heavily.
  • Constraints as suggestions. "Try not to add dependencies" invites one. "No new dependencies" does not.
  • Asking for everything. "Fix it, add tests, update docs, and refactor" produces a shallow version of each. Split it.

Quick check

  1. Which part lets an agent verify its own work?Done when: a runnable, specific, cheap check.

  2. Rewrite "Clean up the logging" as an outcome.For example: "Every log line in src/api uses the shared logger with a request_id field, and no print() calls remain."

  3. When can you skip most of the five parts?For small, unambiguous tasks such as a one-line fix with an obvious test.

Continue exploring

CourseCover image for Agent Building Blocks: Skills, Subagents, MCP and Hooks

Agent Building Blocks: Skills, Subagents, MCP and Hooks

A free, hands-on course on the four pieces behind Cursor and Claude Code agents: skills, subagents, MCP servers and hooks. Build each one, then combine them.

Agent Skills
Chat & AI
+1

9 chapters · 30 min

BlogCover image for 17 Thinking Skills for AI Agents: Pre-Mortem, Five Whys, Six Hats and More

17 Thinking Skills for AI Agents: Pre-Mortem, Five Whys, Six Hats and More

AI Apps & Assistants
Agent Skills
4 min read
ToolCover image for AI Token Counter

AI Token Counter

AI token counter with model pricing and context-window comparison in your browser.

Chat & AI
AI Apps & Assistants
+1
Productskills.sh+1Claude Code Subagents for Cursor

Claude Code Subagents for Cursor

Your Cursor subagents can finally run on the model you picked in each agent file.
Chat & AI
Agent Skills
AI Apps & Assistants
Bash
BlogCover image for How to Install Caveman in Cursor and Claude Code

How to Install Caveman in Cursor and Claude Code

AI Apps & Assistants
Agent Skills
+1
3 min read
BlogCover image for Publish AI Agent Skills to ClawHub: Stop Re-Pasting Your AI Workflow

Publish AI Agent Skills to ClawHub: Stop Re-Pasting Your AI Workflow

AI Apps & Assistants
Agent Skills
3 min read