Claude Agent Code Patterns: Prompts, Tools, and Context

Once you've shipped a few agents on Claude, you stop thinking in terms of one-off prompts and start thinking in patterns — the same handful of structural moves that show up in every reliable agent and the same anti-patterns that show up in every flaky one. This post collects the code-level patterns I reach for repeatedly when building enterprise agents: how to structure prompts, how to shape tool schemas, and how to manage the context window as a scarce resource rather than an infinite bucket.

None of these are framework-specific. They apply whether you're on the Claude Agent SDK, raw Messages API, or something in between. They're about how you organize the inputs to the model so its outputs stay predictable.

Pattern: layer the prompt by stability

Treat the prompt as layers ordered by how often they change. The most stable layer is the agent's identity and hard rules — this almost never changes. Below it sits task-specific guidance that changes per feature. Below that, dynamically retrieved context that changes every turn. Keeping these as distinct, clearly delimited sections — not one run-on blob — makes the prompt easier to reason about and lets you cache the stable parts.

That caching point is real money. Because the stable system layer is identical across many requests, prompt caching lets Claude reuse it instead of reprocessing it every call, which cuts both latency and cost on high-volume agents. If you interleave volatile and stable content, you forfeit the cache. So structure the prompt stable-first, volatile-last, and you get correctness and economics from the same decision.

Pattern: tools as a typed, self-documenting contract

The strongest lever on agent reliability is tool schema quality. Write each tool definition as if the only documentation the model will ever get is that schema — because it is. Use precise names, mark required versus optional fields, constrain enums instead of accepting free strings, and describe the return shape so the model knows what it'll get back. A returns tool whose status field is an enum of eligible, out_of_window, and already_returned produces far steadier behavior than one that returns a free-text status string.

flowchart TD
  A["Incoming request"] --> B["Stable layer: identity + hard rules (cached)"]
  B --> C["Task layer: feature guidance + skill"]
  C --> D["Dynamic layer: retrieved facts + history"]
  D --> E{"Claude plans next action"}
  E -->|Tool| F["Typed tool schema + validation"]
  E -->|Answer| G["Structured output check"]
  F --> D
  G --> H["Return + trace"]

The diagram shows the layered prompt feeding a planning step that either calls a typed tool or emits a checked answer. The two patterns reinforce each other: a clean layered prompt helps the model plan, and a typed tool contract keeps the plan executable.

Pattern: make the model emit structured output you can verify

When an agent's answer needs to drive downstream code — set a ticket priority, fill a form, route a case — don't parse free text. Ask Claude to return a specific structure and validate it before you act on it. If the structure is malformed or violates a constraint, you can reflect the error back to the model and let it correct, rather than shipping a broken value downstream. This validate-and-reflect loop turns the occasional malformed output into a self-healing event instead of a production incident.

The key is that validation lives in your code, deterministically, not in a hopeful instruction buried in the prompt. "Always return valid JSON" is a wish; a parser that rejects invalid output and asks again is a guarantee. Build the guarantee. Cap the number of correction attempts so a stubbornly malformed response fails loudly instead of looping forever.

Pattern: budget the context window deliberately

A large context window is a temptation, not a free lunch. As context grows, two things happen: cost rises linearly, and the model's attention to any single fact gets diluted. The pattern is to treat context like a tight budget — include exactly the documents, history, and tool results the current step needs, and nothing more. Retrieve the three most relevant policy snippets, not the entire policy manual.

For long-running agents, pair this with summarization. When a sub-task completes, compress its full transcript down to the durable facts and drop the rest from the working context. The agent keeps the conclusion — "customer verified, order 4821 confirmed eligible" — without dragging the whole back-and-forth forward. This keeps later turns sharp and cheap, and it's the difference between an agent that gets smarter as a task progresses and one that gets foggier.

Pattern: separate capability from competence with skills

An Agent Skill is a self-contained folder of instructions, scripts, and resources that Claude loads dynamically when a task calls for it, teaching the model how and when to use a capability. The pattern here is to keep raw capability — the tool that does the thing — separate from competence — the know-how about when and how to do it well. The tool lives behind an MCP server; the procedure lives in a skill.

This separation lets you improve an agent without touching its tools. If support discovers a better way to phrase return denials, you update the skill, not the returns API. If the returns API gains a field, you update the tool schema, not the prose. Two independently versioned units, each owned by the team best suited to it. At enterprise scale this is what lets dozens of agents share connectors while each carries its own domain-specific judgment.

Pattern: fail toward the human, not toward a guess

The last pattern is a posture more than a snippet. Design every uncertain branch to escalate rather than improvise. When the model lacks a tool result it needs, when validation fails repeatedly, when confidence is low, or when the request touches money or safety, the right move is to hand off to a human with full context attached — not to produce a plausible-sounding guess. Encode this as explicit escalation paths in both the prompt and the harness, and make handoff a first-class outcome you measure, not a failure you hide.

Frequently asked questions

How should I structure an agent's prompt?

Layer it by stability: a fixed identity-and-rules layer, a task-specific guidance layer, and a dynamic retrieved-context layer. Put stable content first so prompt caching can reuse it, and keep the layers clearly delimited rather than merged into one blob.

What makes a tool schema reliable?

Treat the schema as the model's only documentation. Use precise names, constrain enums instead of free strings, mark required fields, and describe the return shape. Constrained, self-documenting schemas produce far steadier tool use than vague ones.

How do I keep agent output safe to act on?

Ask for a specific structure and validate it deterministically in code before acting. On a violation, reflect the error back to the model for a bounded number of correction attempts rather than trusting a prompt instruction to guarantee valid output.

What's the difference between a tool and a skill?

A tool is raw capability — the function that performs an action, usually behind an MCP server. A skill is competence — a loadable folder of instructions teaching the model when and how to use that capability well. Keeping them separate lets you improve judgment and capability independently.

Bringing agentic AI to your phone lines

CallSphere applies these same patterns — layered prompts, typed tool contracts, tight context budgets, and human escalation — to voice and chat agents that handle live conversations and book work without dropping the ball. See the patterns at work at callsphere.ai.

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.