Why Agents Fail: A Claude Skill for Agent Prompt Design

Agent prompts fail less from weak instructions than from overlapping tools, context that piles up until the contract is forgotten, and no definition of "done" or "stuck." The Agent Prompt Architecture skill treats the system prompt, tools, and context budget as one system and designs them with a seven-stage protocol.

Why do agent prompts fail when chat prompts don't?

Most prompt advice treats the system prompt as a text block: write a clear role, add examples, be specific. That helps with a chat answer, but agents fail in ways text-block advice doesn't cover. I kept seeing the same three failures:

• An agent with overlapping tools calls the wrong one and stalls the run.
• On a long task, context piles up until the model stops recalling the contract it was given.
• A run never ends, because nobody defined what "done" or "stuck" looks like.

What is the core idea of the skill?

System instructions, tool definitions, retrieved context, and message history all consume the same finite attention budget. The skill treats the agent's prompt as part of that complete context system and enforces a protocol for designing it before a single tool call happens.

Ask Claude to "design an agent that resolves tier-1 support tickets," "review this agent's system prompt and tool set," or "why does this agent keep looping?" and it runs the protocol instead of giving a generic rewrite.

What are the seven stages?

Stage	What Claude does	Failure it prevents
1. Agent contract and boundary	Defines the task, verifiable success criteria, non-goals, an escalation path, and the working "altitude"	Vague guidance that assumes shared context; hardcoded if-else logic
2. Context budget and curation	Keeps the contract, role, and tool schemas always loaded; references documents and logs by identifier and loads them just in time	Context rot, where recall drops as token count rises
3. System prompt structuring	Sections for background, instructions, tool guidance, and output contract; direct verbs, one role, three to five canonical examples	A laundry list of edge cases
4. Tool contract engineering	Consolidates and namespaces tools, adds actionable error messages, checks that each tool has one obvious purpose	Overlapping tools, ambiguous parameters, unbounded responses
5. Stop conditions and escalation	Defines success, failure, retry-class, budget, stagnation, and ask-when-blocked conditions, each with a trigger and an action	"Retry until context runs out"
6. Evaluation-driven iteration	Uses a fixed task set, tool-call metrics alongside accuracy, and a held-out test set	Shipping a prompt nobody measured
7. Anti-patterns	Prohibits prompt-as-programming, bloated tool sets, silent context accumulation, unverified "done," unobservable runs, and blind retries	Repeating known failure modes

Why is the tools table where agents actually fail?

Tools are the part of an agent prompt that gets the least design attention. Overlapping purposes, ambiguous parameter names, returns full of UUIDs, and unbounded responses all burn the attention budget or send the agent down the wrong path. Stage 4 consolidates and namespaces tools, then validates that each has one obvious purpose.

How does the context budget work?

Every token must justify its place. The always-loaded block holds the contract, role, and tool schemas. Repositories, documents, and logs are referenced by lightweight identifiers and loaded just in time through tools.

Anthropic's work on context engineering shows recall precision drops as token count rises, so the prompt's job is to stay minimal, not comprehensive. The always-load block sits first and stays byte-identical between turns so the provider's prompt cache hits it, and the stage sets a per-run cost and latency target before a model is chosen.

What does the skill do about stop conditions?

It splits stop conditions into two groups. Some a prompt can self-check: success, stagnation, and ask-when-blocked. Others only an orchestration loop can enforce: retry and backoff, history compaction, and hard budgets. Transient failures get capped backoff, and terminal ones escalate with no retry. Without these, an agent's default is to retry until context runs out. With them, the run terminates on evidence.

What worked examples are included?

The skill ships with four:

1. A support-agent system prompt built from scratch.
2. A tool mis-selection fix.
3. A long-running coding harness split into initializer and coding sessions.
4. A retrofit of a brittle prompt that hardcodes conditions it should delegate.

How do I install it?

1. Download agent-prompt-architect.md.
2. Save it as .claude/skills/agent-prompt-architect/SKILL.md in your project or in ~/.claude/skills/.
3. Ask Claude to design or review an agent prompt.

More skills are in the GitHub repository. The Context Engineer generates skills like this from a goal description.

FAQ

What is the "right altitude" for an agent prompt?

Specific enough to constrain behavior, flexible enough for the model to use judgment. The skill checks instruction prose against this, rejecting both hardcoded if-else chains and vague guidance.

Why do agents pick the wrong tool?

Usually because tool purposes overlap or parameter names are ambiguous. Consolidating tools and giving each one obvious purpose fixes more of this than rewording the instructions.

Where should stop conditions live?

Self-checkable ones (success, stagnation, ask-when-blocked) belong in the prompt. Retry and backoff, history compaction, and hard budgets belong in the orchestration loop.

Does this need an API key or package?

No. It is a single SKILL.md file that Claude loads locally.

Related: Subagent Dispatch Economics covers the decision to delegate work to another agent. This skill was first shared on r/PromptEngineering by u/Parking-Kangaroo-63.