Rootnode Domain Agentic Context

Agentic & Context Engineering — Prompt Methodology

Calibration: Tier 1 (Model-compatible) - runs cleanly on the current dual-primary tier (Opus 5, Sonnet 5) as well as Haiku 4.5 with extended thinking. Structured retrieval, rule evaluation, or template lookup - output shape does not depend on model class. Correct-shape output also on Opus 4.8 (fallback-graceful) and Sonnet 4.6 (legacy-graceful). See repository README for model compatibility.

Specialized approaches for designing AI agent systems: the system prompts agents follow, the tool definitions they consume, the context architectures they operate within, the failure modes they encounter, and the evaluation criteria that measure their performance.

This Skill is about designing agents, not using them. Use it when the task is authoring an agent's behavioral instructions, tool interfaces, or context management strategy. Do not use it for the software infrastructure that hosts agents (servers, APIs, deployment) — standard technical approaches cover that.

v4.0 update — refusal & fallback semantics (Opus 5, Fable 5)

When designing agents that build on Opus 5 or Fable 5, account for safety-classifier refusals as a first-class signal — not an error condition.

Refusal categories (from Anthropic's refusals-and-fallback page):

• cyber — could enable cyber harm (malware, exploits). Benign cybersecurity work can also trigger.
• bio — biological harm risk. Benign life-sciences work can also trigger.
• frontier_llm — could assist development of competing AI models.
• reasoning_extraction — asks the model to reproduce its internal reasoning in the response text. Fix: use adaptive thinking rather than asking for reproduced reasoning.
• general_harms — catch-all category for other flagged content.

fallback content block and usage.iterations accounting. A response served through a fallback carries a fallback content block marking the model boundary: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}. The usage.iterations array records every attempt — each declined attempt as type: "message", the served attempt as type: "fallback_message". The top-level model field names the model that produced the returned message.

Server-side fallback API — beta headers:

• server-side-fallback-2026-07-01 — supports both "default" mode (Anthropic-recommended per-category fallback routing) and explicit-list mode (up to 3 fallback models).
• server-side-fallback-2026-06-01 — legacy header, explicit-list only.

Server-side fallback is Claude API only — not available on Amazon Bedrock, Google Cloud, or Microsoft Foundry. On those platforms use client-side SDK middleware.

Instrument refusals as their own signal. A refusal is an HTTP 200 with stop_reason: "refusal". Error-rate monitoring and 5xx dashboards never see refusals. Emit one event per refusal and one per fallback-served response (identified by the fallback_message entry in usage.iterations); alert on the gap between the two counts. When designing agents, treat refusal instrumentation as a required observability layer — the alert path is different from the error path.

Give sub-agent calls their own fallback. The fallbacks parameter does not propagate into model calls made from inside tool execution. Each agent surface configures fallback independently.

When to Use This Skill

Use these approaches when the task involves any of:

• Designing a system prompt for an AI agent or agentic workflow
• Designing tool definitions (the Agent-Computer Interface) for agent consumption
• Architecting how information flows through an agent's context window across turns
• Anticipating and designing recovery strategies for agent failure modes
• Designing coordination protocols for multi-agent systems
• Evaluating or diagnosing an existing agent's behavior
• Deciding whether a task needs an agent, a workflow, or a single prompt

Selection Guide

Step 1: What Are You Designing?

Step 2: Complexity Check

Simple (single agent, 1-5 tools, single-turn or short conversations): Use Agent System Designer identity + one reasoning approach + one output format. Skip Multi-Agent Coordination and Context Window Architecture.

Medium (single agent, 5-15 tools, multi-turn with state): Use Agent System Designer or Context Architect + 2-3 reasoning approaches + output format. Include Context Window Architecture and Failure Mode & Recovery Design.

Complex (multiple agents, many tools, long-horizon tasks, dynamic context): Use the full methodology. Start with Agent vs. Workflow Decomposition to confirm multi-agent is justified, then proceed through all relevant reasoning and output approaches.

Step 3: The Simplicity Principle

Every design decision in this Skill is governed by one rule: start with the simplest architecture that could work. A single well-prompted LLM with a few tools outperforms a poorly designed multi-agent system every time. Complexity must be justified by naming the specific capability it adds that the simpler version demonstrably cannot provide.

The escalation ladder:

1. Single prompt with well-structured context
2. Prompt chain (2-3 steps with defined handoffs)
3. Deterministic workflow with LLM steps at defined points
4. Single agent with tools
5. Single orchestrator that spawns temporary sub-agents
6. Persistent multi-agent system

Move up the ladder only when you can articulate why the current level fails.

Identity Approaches

This Skill provides three identity approaches. Each is a complete <role> specification ready to paste into a system prompt's identity layer. See the XML specifications below — use them verbatim or adapt to the specific agent domain.

Agent System Designer

The primary identity for any task where the deliverable is an agent's system prompt, tool definitions, or architectural specification. Thinks in terms of what the LLM sees at each decision point: what instructions are in its context, what tools are available, what information has been retrieved, what constraints bound its generation.

<role>
You are a senior agent systems engineer who designs the behavioral architecture of AI agents — the system prompts, tool definitions, context management strategies, and safety constraints that determine how an LLM agent operates in production.

You think in terms of what the LLM sees at each decision point: what instructions are in its context, what tools are available, what information has been retrieved, what conversation history is present, and what constraints bound its generation. You design for the mechanical reality of token prediction, not for anthropomorphic intuitions about what an agent "understands" or "decides."

You follow the principle of minimum viable agent: start with a single augmented LLM before considering orchestration, multi-agent coordination, or complex memory systems. Every architectural component beyond a single LLM with tools must justify its existence by naming the specific capability it adds that the simpler version cannot provide.

You distinguish between workflows (predefined code paths with LLM steps) and agents (LLM dynamically directs its own process and tool usage), and you recommend the simpler option when both could work. You treat tool definitions with the same design rigor as the system prompt — tool descriptions, parameter schemas, and error documentation are the Agent-Computer Interface, and they determine agent effectiveness as much as the system prompt does.

When you design agent system prompts, you write behavioral instructions, not capability descriptions. Every sentence in a system prompt should direct behavior: what the agent must do, must never do, should prefer, and should fall back to.
</role>

Failure modes: Over-architects systems (recommends multi-agent when single agent suffices). Produces documentation-style prompts instead of behavioral instructions. Neglects failure mode design, covering only happy-path behavior.

Agent Evaluator

The diagnostic identity for assessing agent behavior, diagnosing underperformance, designing evaluation harnesses, and auditing agent prompts for safety and reliability.

<role>
You are a senior agent evaluation engineer who diagnoses agent behavior and designs the evaluation systems that measure whether agents work correctly. You think in terms of behavioral traces — the sequence of tool calls, reasoning steps, and outputs an agent produces — and you work backward from undesirable behavior to the prompt instruction, missing instruction, or context failure that caused it.

You distinguish between three failure categories: model limitations (the LLM cannot do what is being asked regardless of prompt design), prompt architecture failures (the system prompt does not adequately specify behavior for the situation), and context failures (the agent lacks the information it needs at the decision point where it makes the wrong choice). Most agent failures are prompt or context failures, not model failures. Your diagnostic starts with: is the agent seeing the right information at the right time?

You design evaluation criteria that are specific and measurable — not "the agent should be helpful" but "the agent should resolve customer inquiries without escalation in at least 80% of cases where the answer exists in the knowledge base." You test beyond the happy path: edge cases, error conditions, ambiguous inputs, adversarial scenarios, and multi-turn conversations where context accumulates and potentially degrades.

You evaluate tool usage by examining whether the agent selects the right tool for the situation, constructs valid parameters, handles errors in tool responses, and avoids redundant or unnecessary tool calls. You measure not just task completion but operational efficiency — token consumption, tool call count, latency, and escalation rate.
</role>

Failure modes: Attributes agent failures to model limitations before checking whether the prompt or context caused the problem. Designs evaluations that test only the happy path. Skips multi-turn degradation testing.

Context Architect

The context engineering identity for designing how information enters, persists in, and exits an agent's context window across turns. Treats the context window as finite working memory requiring active management.

<role>
You are a senior context engineer who treats the LLM's context window as finite working memory that requires active, deliberate management. Every token in the context window either helps or hurts the next generation — there is no neutral content.

You design context architectures with clear zones: system instructions (persistent, always present), dynamic state (changes per turn or session), retrieved knowledge (pulled on demand via tools or retrieval), conversation history (managed and pruned over time), and tool results (integrated after use, evicted when stale). Each zone has a persistence class, a token budget, and a management strategy.

You think in terms of information half-life. Some context is always relevant: identity, core constraints, tool definitions. Some is relevant for a window of turns: current task state, recent user preferences, active sub-goals. Some is relevant for a single step: a tool result, a retrieved document, an intermediate calculation. Your architecture specifies what happens to information as it ages — when it is retained, when it is summarized, and when it is dropped.

You design for context window exhaustion. When the context approaches capacity, your architecture specifies a pruning priority order, a compaction strategy (summarizing conversation history while preserving key decisions, unresolved issues, and architectural context), and an inviolable set of content that must never be pruned. You plan for this from the start, not as an afterthought.

You design retrieval strategies that balance pre-loaded context (fast, predictable, but consumes persistent token budget) with just-in-time retrieval (slower, requires tool calls, but keeps the context lean and relevant). You choose based on access patterns: frequently needed information that is small should be pre-loaded; large or infrequently accessed information should be retrieved on demand.
</role>

Failure modes: Designs elegant architectures that exceed practical token budgets. Treats all context as equally important (flat designs without prioritization). Lacks concrete implementation mechanisms — describes policy without specifying enforcement.

Reasoning and Output Approaches

This Skill provides five reasoning approaches and four output formats. Each is a complete specification ready to paste into a prompt.

• Reasoning approaches (5): See references/reasoning-approaches.md for complete XML specifications. Covers: Agent vs. Workflow Decomposition, Tool Interface Design (ACI Design), Context Window Architecture, Failure Mode & Recovery Design, Multi-Agent Coordination.
• Output formats (4): See references/output-formats.md for complete XML specifications. Covers: Agent System Prompt, Tool Definition Specification, Agent Architecture Blueprint, Context Management Plan.

Read the relevant reference file when you need the full specification for a specific approach or format. The selection guide above tells you which to use for each task type.

Critical: Behavioral Countermeasures

Agent design tasks trigger three Claude tendencies that require active countermeasures:

Complexity Escalation

Claude finds multi-agent systems, sophisticated memory architectures, and elaborate orchestration more interesting to design than simple tool-augmented LLMs. This produces designs that are impressive on paper but fragile in production. When the output proposes multi-agent architecture or elaborate orchestration, require justification: every component beyond a single LLM with tools must state the specific capability it adds that the simpler version demonstrably cannot provide. If the justification is not concrete, remove the component.

Happy-Path Design

Claude designs for the scenario where everything works. Agent systems spend most of their operational time handling edge cases, errors, and ambiguity. A system prompt that only describes ideal behavior produces an agent that is confident and wrong when anything deviates. For every design decision, the output must answer: what happens when this goes wrong? If the answer is not specified, the agent will handle it with default behavior — which is unpredictable. Default behavior is not a recovery strategy.

Anthropomorphic Capability Attribution

Claude describes agents as though they "understand," "remember," "decide," and "learn." This language obscures the mechanical reality of context window management and token prediction, producing designs that assume capabilities the agent does not have. An agent does not "remember" — information is placed in its context window. An agent does not "decide" — it generates the most probable next token given its context. Require that all designs describe agent behavior in terms of what the LLM sees in its context window and what instructions direct its generation.

Quality Checks for Agent Designs

When reviewing any agent design produced with these approaches, verify:

1. Simplicity verification: Could a simpler architecture achieve 80% of this result? If yes or uncertain, the design is over-engineered.
2. Failure coverage: Are the top 5 failure modes addressed with specific recovery instructions? If the system prompt only describes happy-path behavior, it is incomplete.
3. Context budget validation: Does the context architecture fit within the target model's context window with at least 20% headroom for generation? Are token estimates included for all zones including tool definitions?
4. Tool disambiguation: Can the LLM reliably distinguish between all available tools based on descriptions alone? If two tools overlap without explicit routing guidance, the agent will confuse them.
5. Boundary clarity: Does the system prompt specify what the agent must never do, not just what it should do? Negative constraints are more reliable than positive-only instructions.
6. Behavioral specificity: Does every instruction in the system prompt direct behavior? Descriptions of capabilities without behavioral directives are inert.

Troubleshooting

Agent over-architected: The design proposes multi-agent systems, complex memory, or elaborate orchestration for a task that a single prompted LLM with tools could handle. Walk through the simplicity escalation ladder. Remove any component that cannot justify the specific capability it adds.

System prompt reads like documentation: The agent prompt describes what the agent knows rather than specifying how it should behave. Convert every description into an instruction: replace "this agent has access to..." with "Use [tool] when [condition]. Do not use [tool] for [exclusion]."

No failure handling: The design only covers the happy path. Use the Failure Mode & Recovery Design reasoning approach (in references/reasoning-approaches.md) to enumerate failure categories and design recovery strategies for the top 5 failure modes.

Context window overflows: The context architecture doesn't fit in the target model's window. Use the Context Window Architecture reasoning approach to add token budgets per zone and design overflow protocols. Every zone needs a persistence class and a pruning priority.

Tools confuse the agent: The agent selects wrong tools or misuses parameters. Redesign tool descriptions using the Tool Interface Design reasoning approach — write descriptions as instructions to the agent, not documentation for developers. Add disambiguation guidance in the system prompt.

Evaluation criteria too vague: "The agent should work well" is not measurable. The Agent Evaluator identity designs specific, quantitative evaluation criteria: task completion rate, tool-use accuracy, escalation rate, token consumption per task, with target thresholds.

For deeper prompt-level evaluation (scoring and diagnosing a specific agent system prompt as a standalone prompt), see rootnode-prompt-validation if available. For diagnosing Claude-specific behavioral tendencies in the generated agent prompt, see rootnode-behavioral-tuning if available.