Three agent failures show up in almost every postmortem: wrong tool called, context turned to mush, and no one ever defined “done.” u/Parking-Kangaroo-63, posting in r/PromptEngineering, got tired of watching it happen and built a fix. This Redditor treats an agent’s system prompt as a full context system, not a paragraph of instructions.
That’s the real shift here. Most prompt advice still treats a system prompt like a single text block: write a role, add examples, be specific. This skill argues that’s the wrong unit of design.
System instructions, tool schemas, retrieved documents and message history all draw from one finite attention budget. The prompt has to be architected alongside the tools and the memory, not written in isolation. Anthropic’s own context engineering research backs this up: recall precision drops as token count climbs, so the goal is minimal tokens, not comprehensive ones.
Here’s the twist: the skill splits stop conditions into two buckets, and most people never separate them. Some conditions, like success, stagnation, and “ask when blocked,” are things the prompt itself can check mid-run. Others, like retry backoff, trimming old history, and hard token budgets, can only be enforced by the orchestration harness around the model. Bake harness-only logic into the prompt and you get an agent that “knows” it should stop but has no mechanism to actually do it. Ask a model to “back off and retry” without a real backoff loop behind it, and it just keeps calling the same broken tool until the run dies on its own.
How the seven-stage protocol runs
Ask Claude to design or review an agent and it works through a fixed sequence instead of freehanding a rewrite. The condensed version:
- 🧩 Contract first. Task, success criteria, non-goals, and an escalation path, defined before any instructions get written.
- 💰 Budget the context. Always-load tokens like the contract and tools sit in a cache-stable prefix. Everything else loads just-in-time through tools.
- 📐 Structure the prompt. Background, instructions, tool guidance, and an output contract, each in its own section with three to five canonical examples.
- 🔧 Fix the tool contract. One clear purpose per tool, readable return values, and error messages that say how to fix the call.
- Set stop conditions. Success, failure, retry class, budget, and stagnation, each mapped to a trigger and an action.
Stage six forces evaluation before shipping: a fixed task set, tool-call metrics next to accuracy, and a held-out test so nobody ships on vibes. Stage seven is a straight list of anti-patterns. Things like silent context accumulation, premature “done” declarations, and blind retries on errors that were never going to succeed anyway.
Four tables carry the actual decision logic instead of leaving it to judgment on every run. One maps where each context component gets loaded. Another checks whether the prompt is pitched at the right altitude. The last two are a tool selection matrix and the stop condition table.
Here’s the contract skeleton the skill has the model fill in first:
Agent Contract
Task: [one sentence]
Success Criteria: [observable conditions]
Non-Goals: [explicit prohibitions]
Escalation: [what to do on failure or out-of-scope requests]
Altitude: [principles vs. step-by-step procedure]
Instrumentation: [reasoning stated before tool calls; the trace the harness records]
Four worked examples ride along with the skill:
- A support agent built from scratch.
- A tool mis-selection fix on an agent that kept opening one huge log file.
- A long-running coding harness split into initializer and coding sessions.
- A retrofit of a prompt that hardcoded ten if-else branches.
Pro tip
Start with stage four before you touch stage three. Most agent debugging sessions end up back at the tool descriptions anyway. If two tools have overlapping purposes or a return value full of raw IDs, no prose in the system prompt will fix it.
Second tip: keep the always-load block byte-identical between turns. That single layout choice is what lets the provider’s prompt cache actually hit, and it’s the cheapest latency win most agent builds skip entirely.
One caveat before you adopt this wholesale. It’s a design protocol, not a plug-in fix. It still asks for real evaluation work: a fixed task set, a held-out split, and someone reading transcripts instead of chasing a single score. A few conditions in the stop-condition table, like retry backoff and history compaction, only work if your harness actually implements them. The skill is explicit that a prompt can’t enforce what only the orchestration loop controls. If your agent runs on a thin script with no retry or compaction logic, half the stop-condition table sits there unused until you build the plumbing.
The full skill.md is posted in the thread, ready to drop into a Claude setup as is. This Redditor also built a platform that generates skills like this one from a goal description and checks them against behavioral benchmarks, worth a look if you design agents for a living.
Go read the whole thread. It’s a genuinely useful checklist for anyone whose agent keeps looping, mis-firing tools, or declaring victory too early 🏴☠
Agent Prompt Architecture skill.md
by u/Parking-Kangaroo-63 in PromptEngineering