How to Write a Claude Agent Prompt That Finishes the Job

Your Claude agent produces output that's technically correct but reads like it was written by a committee, or it stops halfway through a task and waits for you to nudge it forward. Either way, you're back to being the quality check on work you handed off precisely so you could stop checking. The fix is rarely a longer prompt with more rules — it's a better-designed instruction set that treats the model as smarter than the words you feed it.

Quick answer: A good Claude agent prompt anchors the agent's role in one to three sentences, separates instructions, context, and examples with XML-style tags, frames tool use as conditional guidance ("use when needed") instead of absolute rules, puts key reminders at the bottom for recency, and builds in recovery steps so the agent retries instead of halting. Design the environment the agent works in, not every behavior you want.

Why your Claude agent produces generic output

Generic output usually means the agent has no anchored point of view, so it defaults to the safest, blandest version of the answer. The model is capable of sharp, specific work — the prompt just never told it who it is or what "good" looks like for this job. The team behind buildfastwithai put it bluntly: Claude takes you literally. If you write "help with customer emails," you get help-with-customer-emails energy: correct, forgettable, and shaped like every other support reply on the internet.

The counterintuitive lesson from people who have reverse-engineered how Claude Code itself is prompted is that the model is smarter than your prompt. Your job is not to script every move. It's to design the environment — the role, the context, the examples, the tools, and the escape hatches — and let the model's intelligence do the rest. An Indie Hackers deep-dive on this made the point that every line in a system prompt earns its place; bloated instructions fight the model instead of steering it. If you've watched Claude Code lose the thread mid-session, the same root cause is at work, and it's more about context than the model.

Anchor the role in one to three sentences

The role is the single highest-leverage part of a Claude agent prompt, and it should take one to three sentences, not a paragraph of adjectives. State who the agent is, what it's responsible for, and what a good outcome looks like — then stop. A tight anchor gives the model a stable identity to reason from, which is what kills the generic-committee tone.

Compare these two openings for a support-triage agent.

The vague version: "You are a helpful assistant that handles customer support tickets professionally and thoroughly."

The anchored version: "You are the first-line support agent for a dental practice. You resolve billing and scheduling questions directly, and you escalate anything clinical to a human. A good reply is under 120 words, cites the patient's specific appointment, and never guesses at medical advice."

The second one is shorter on fluff and longer on decisions the agent can actually act on. "Under 120 words" is checkable. "Escalate anything clinical" is a hard boundary. "Never guesses at medical advice" is a guardrail the model can hold. That's the difference between describing a personality and defining a job.

Use XML-style tags to separate instruction, context, and examples

Claude was trained to respond well to XML-style tags, so wrap each part of your prompt in its own labeled block instead of running everything together as one wall of text. Anthropic's own prompt-engineering documentation recommends tags like <instructions>, <context>, and <example> because they let the model tell the difference between a rule it must follow and a sample it should learn from. Mix those together and the agent may treat your example data as a live instruction.

Here's the shape of a tagged prompt:

<role>
You are the intake agent for an HVAC company. You collect the caller's issue, address, and preferred time, then create a job in the CRM.
</role>

<context>
Service area: 30-mile radius of the shop. Emergency jobs (no heat, gas smell)
get same-day priority. Business hours are 7am-6pm.
</context>

<instructions>
1. Confirm the address is inside the service area before booking.
2. For emergencies, offer the earliest same-day slot.
3. Read back the appointment details before ending.
</instructions>

<example>
Caller: "My furnace died and it's freezing."
Agent: "That's an emergency — I can get a tech out today. What's your address?"
</example>

The tags cost you almost nothing and buy you an agent that stops confusing its reference material with its marching orders. This matters more as the prompt grows: a three-line prompt survives without structure, but a working business agent with context, rules, and examples falls apart without it.

Give tool guidance as conditions, not absolute rules

Tell the agent when to reach for a tool, not that it must always use one. Absolute "you MUST call the search tool before every response" rules are how you get an agent that burns tokens and time calling tools it doesn't need — or worse, an agent that freezes when a MUST rule can't be satisfied. Conditional framing ("use the CRM lookup when the caller references an existing account") lets the model apply judgment, which is the whole reason you're using a model and not a flowchart.

This is the same discipline that separates a Zapier automation from a real agent. A rigid rules engine does exactly what you wrote, including the wrong thing; an agent decides. If you find yourself writing a MUST rule for every branch, that's a signal you're scripting behavior a fixed automation should handle instead. Reserve absolute rules for genuine guardrails — "never share another customer's data," "always escalate clinical questions" — and leave the operational choices conditional.

A quick way to sort your rules:

If a rule is about what's allowed, make it absolute. If it's about what's smart in this moment, make it conditional and trust the model.

Put your most important reminders at the bottom

Reminders placed near the end of the prompt carry more weight, because models attend more strongly to recent tokens — the recency effect. If there's one behavior your agent keeps forgetting halfway through long tasks, restate it in a short block at the very bottom of the prompt, after your examples and context. This is the cheapest fix for an agent that starts strong and drifts.

A closing reminder block might be three lines:

<reminders>
Keep replies under 120 words. Escalate anything clinical. Read back
appointment details before ending the call.
</reminders>

You're not repeating the whole prompt. You're re-surfacing the two or three things that matter most, in the position where the model is most likely to hold them through a long exchange. The aifire team's "golden rules" write-up lands on the same tactic: put the non-negotiables where recency works in your favor.

Embed recovery loops so the agent stops halting

An agent that halts mid-task usually hit an error, got an empty result, or reached an ambiguous branch with no instruction for what to do next — so it stopped and waited for you. The fix is to write the recovery path directly into the prompt: tell the agent what to do when a tool fails, when data is missing, or when it's unsure. Give it permission to retry, to try an alternative, or to make a documented assumption and keep going.

A recovery block looks like this:

<recovery>
If a tool call fails, retry once. If it fails again, note the failure and
continue with the rest of the task — do not stop.
If required information is missing, ask one specific follow-up question,
then proceed with what you have.
If a request is ambiguous, state your assumption and continue rather than
halting.
</recovery>

This single block eliminates most of the "why did it just stop?" frustration. The agent no longer treats every snag as a full stop. It treats snags as branches with defined exits. That's what "stop being the quality check" actually requires — an agent that finishes the job and flags what went sideways, instead of one that pauses and hands the work back to you at the first bump. The controlled-rollout approach that stackai and pylon converge on for support agents is the same idea at the process level: define what "resolved" means, then let the agent run within gates rather than babysitting every ticket.

Manual prompting vs a designed environment

Most founders write agent prompts the way they'd write a task list for a new hire on day one: a long paragraph of everything they can think of. That's the manual way, and it produces the two failures this post opened with. A designed environment produces an agent you can actually trust with a workflow.

The manual way isn't wrong because it's lazy. It's wrong because it fights the model — it tries to script intelligence instead of directing it.

Common pitfalls when writing a Claude agent system prompt

The most common mistake is treating a bad output as a reason to add more rules, when it's usually a reason to fix the structure you already have. Here are the failure patterns that show up most often, and what to do instead.

FAQ

How long should a Claude agent prompt be?

A Claude agent prompt should be as short as it can be while still anchoring the role, giving necessary context, showing one or two examples, and defining recovery behavior. Length isn't the goal — every line should earn its place. A tight, tagged prompt of 30-40 lines will usually outperform a 200-line one because it fights the model less.

Why does my Claude agent keep stopping in the middle of a task?

Mid-task halts happen because the agent hit an error, an empty result, or an ambiguous branch with no instruction for what to do next, so it defaulted to waiting for you. Add a recovery block that tells it to retry once, make a documented assumption, or ask one specific follow-up and then continue — that alone resolves most mid-task halts.

Should I use XML tags in my Claude system prompt?

Yes. Claude responds well to XML-style tags because it was trained on them, and Anthropic's prompt-engineering documentation recommends them for separating instructions, context, and examples. The tags let the model tell a rule it must follow apart from an example it should learn from, which prevents it from treating sample data as a live command.

What's the difference between a guardrail and a conditional rule?

A guardrail is an absolute boundary about what the agent is allowed to do — never share another customer's data, always escalate a clinical question — and it should be written as a hard rule. A conditional rule is about what's smart in the moment, like which tool to call or how much detail to give, and it should be framed as "use when needed" so the model can apply judgment.

If you want the copy-paste prompt templates, live workshops, and 40-50+ ready-made Claude use cases that put these rules to work on real business workflows, join the free Claude Community — it's where founders trade the setups that actually stop them from being the quality check.