Agent Prompt Architecture skill.md

Wanted to share a skill I built for designing and reviewing the prompts that run AI agents. Most prompt engineering advice for agents still 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 watching the same three failures: an agent with overlapping tools calling the wrong one and stalling the run; a long task where context piles up until the model stops recalling the contract it was given; and a run that never ends because nobody defined what "done" or "stuck" actually looks like. The skill treats the agent's prompt as part of a complete context system — system instructions, tool definitions, retrieved context, and message history all consume the same finite attention budget — and enforces a protocol for designing that system before a single tool call happens. How it works in practice: Ask Claude something like "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 instead of a generic rewrite, Claude runs a fixed seven-stage protocol. 1. Agent contract and boundary. Before writing any instructions, Claude defines the task, verifiable success criteria, non-goals, an escalation path, and the working "altitude" — specific enough to constrain behavior, flexible enough for judgment. No hardcoded if-else logic, no vague guidance that assumes shared context. 2. Context budget and curation. Every token must justify its place. The contract, role, and tool schemas are always-loaded; repositories, documents, and logs are referenced by lightweight identifiers and loaded just-in-time through tools. This is the stage that fights context rot — 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 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. 3. System prompt structuring. Sections for background, instructions, tool guidance, and output contract. Direct verbs, one role, sequential steps where order matters, three to five canonical examples instead of a laundry list of edge cases. 4. Tool contract engineering. The tools table is where agents actually fail: overlapping purposes, ambiguous parameter names, returns full of UUIDs, unbounded responses that burn the attention budget. Claude consolidates, namespaces, and adds actionable error messages — then validates each tool has one obvious purpose. 5. Stop conditions and escalation. Success, failure, retry-class, budget, stagnation, and ask-when-blocked conditions — each with a trigger and an action. Transient failures get capped backoff; terminal ones escalate with no retry. Without these, an agent's default is "retry until context runs out." With them, the run terminates on evidence. 6. Evaluation-driven iteration. No prompt ships unmeasured. A fixed task set, tool-call metrics (mis-selection, errors, token spend) alongside accuracy, a held-out test set, and transcript reading instead of score-chasing. 7. Anti-patterns. No prompt-as-programming, no bloated tool sets, no silent context accumulation, no unverified "done," no unobservable runs, no blind retries. The System Prompt / Skill Definition: --- name: "agent-prompt-architect" description: "Architects the system prompt, context budget, and tool contract of an AI agent as one system. Use when designing a new agent prompt, reviewing an existing agent configuration, or debugging an agent that loops, mis-selects tools, or stops without a clear result." --- # Agent Prompt Architecture When a user asks to design, review, or improve the system prompt or tool configuration of an AI agent, the agent must follow this procedure to architect the prompt as part of a complete context system rath