claude-agent-sdk-expert

name	claude-agent-sdk-expert
description	Use when reviewing, debugging, or building AI agents with the Claude Agent SDK (TypeScript or Python). Covers the Agent class, query(), agent.stream(), tool_use, tool schemas, maxIterations, subagents, hooks (PreToolCall, PostToolCall, StopHook), MCP integration, multi-agent coordination, structured output, context window management, stop_reason handling, agentic loop architecture, testing, and observability. Do NOT activate for general Claude API usage without agents, simple messages.create() calls, or non-agent Anthropic SDK usage — use the claude-api skill for those.
version	1.1.0
license	MIT
metadata	{"author":"azizaeffendi","hermes":{"tags":["claude-agent-sdk","anthropic","agent-development","tool-design","multi-agent","mcp","typescript","python","production-agents"],"category":"development","requires_toolsets":["terminal"]}}

Claude Agent SDK Expert

Why This Skill Exists

AI-assisted agent development introduces characteristic failure modes that traditional code review misses. Agents fail silently — they hallucinate tool calls, lose context mid-conversation, swallow errors into infinite retry loops, and produce outputs that look correct but aren't grounded in actual tool results. This skill encodes hard-won patterns from building production Claude agents so you catch these issues before they ship.

Core Principle

An agent is only as good as its tools and instructions. The SDK handles the loop — your job is to give it clear tools, clear prompts, and clear boundaries.

Process

Work through each step below. Step 0 is always loaded. For remaining steps, load the referenced file only if relevant to the current task. Skip steps that don't apply.

Step 0: Known Gotchas (Always Load)

Before any deep review or build, scan for the top 10 most common agent mistakes. These are fast to check and catch the majority of production incidents.

Read file: references/gotchas.md

Quick Scan (Review Mode)

For code reviews, run the static analysis script first to surface mechanical anti-patterns before doing a manual review. This catches issues like missing maxIterations, tool_choice: "any", silent catch blocks, and missing additionalProperties: false.

bash scripts/scan-agent-patterns.sh <target-directory>

Review the output, then proceed with the manual steps below for deeper analysis.

Step 1: Agentic Loop Architecture

Evaluate the core agent loop structure, stop condition handling, and iteration guards.

Read file: references/agentic-loop.md

Step 2: Tool Design & Scoping

Review tool definitions for clarity, scope, and schema quality. Ensure descriptions serve as the primary selection mechanism.

Read file: references/tool-design.md

Step 3: Prompt Engineering for Agents

Assess system prompts, instruction clarity, and few-shot example usage.

Read file: references/prompt-engineering.md

Step 4: Structured Output & Schema Design

Check extraction patterns, schema strictness, and field design.

Read file: references/structured-output.md

Step 5: Context Management

Evaluate context window usage, session management, and information retention strategies.

Read file: references/context-management.md

Step 6: MCP Integration

Review MCP server configuration, tool namespacing, and integration patterns.

Read file: references/mcp-integration.md

Step 7: Error Handling & Reliability

Assess error propagation, validation loops, retry strategies, and escalation triggers.

Read file: references/error-handling.md

Step 8: Hooks & Lifecycle

Review PreToolCall, PostToolCall, and StopHook implementations for correctness and safety.

Read file: references/hooks-lifecycle.md

Step 9: Multi-Agent Patterns

Evaluate coordinator-subagent architecture, context passing, and handoff patterns.

Read file: references/multi-agent.md

Core Instructions

1. Report genuine issues only. Do not fabricate problems. If the code is solid, say so.
2. Prioritize by impact. Critical issues (crashes, infinite loops, data loss) first, style nits last.
3. Skip irrelevant sections. If the agent doesn't use MCP, skip Step 6. If it's single-agent, skip Step 9.
4. Dual mode — review and build.
   • Review mode: Audit existing agent code. Output severity-ranked findings with concrete fixes.
   • Build mode: Help write new agent code. Follow the process steps as a checklist to ensure nothing is missed.
5. Show, don't tell. Every finding or recommendation must include a concrete code example — before/after for reviews, working snippets for builds.
6. Ground in SDK reality. Reference actual SDK APIs (query(), tool_use, stop_reason, hooks, etc.). Do not invent APIs that don't exist.
7. Maintain the review log. After completing a review or build session, append a one-line JSON entry to data/review-log.jsonl:

   {"date":"YYYY-MM-DD","mode":"review|build","project":"project-name","sdk":"ts|py","findings":["finding1","finding2"],"severity_counts":{"critical":0,"high":0,"medium":0,"low":0}}
   

   At session start, if data/review-log.jsonl exists, read it and note recurring patterns across past sessions to inform the current review.

Output Format

Review Mode

Rank findings by severity:

## [CRITICAL] Issue title
**What**: Description of the problem
**Why it matters**: Impact (crashes, data loss, infinite loops, etc.)
**Where**: File and line reference
**Fix**:
// Before (BAD)
<problematic code>

// After (GOOD)
<fixed code>

## [HIGH] Issue title
...

## [MEDIUM] Issue title
...

## [LOW] Issue title
...

Build Mode

Structure output as:

1. Architecture Decision — Which pattern to use and why
2. Implementation — Working code following all best practices
3. Checklist — Verification points from the relevant process steps

Step 10: Testing Agents

Review test coverage, mocking strategies, and non-determinism handling.

Read file: references/testing-agents.md

Step 11: Observability & Monitoring

Check structured logging, cost tracking, and production visibility.

Read file: references/observability.md

When to Use This Skill

Activate whenever the conversation involves:

• Agent, query(), stream(), tool_use, stop_reason, maxIterations — Claude Agent SDK APIs
• PreToolCall, PostToolCall, StopHook — Lifecycle hooks
• Multi-agent coordination, subagent spawning, coordinator patterns
• MCP server configuration (.mcp.json, mcpServers)
• "Why is my agent looping?", "Why did my agent stop?", "My tool isn't being called"
• Writing or reviewing any file that imports from @anthropic-ai/sdk Agent class

Do NOT activate for:

• Simple messages.create() without an Agent class
• Non-agent Anthropic API usage
• General TypeScript/Python code review without agent context

Quick Reference

# Run static analysis first (always do this before manual review)
bash claude-agent-sdk-expert/scripts/scan-agent-patterns.sh ./your-agent-project

# Find all Agent instantiations (check each for maxIterations)
grep -rn "new Agent(" . --include="*.ts" --include="*.js" --include="*.py"

# Find potential silent failures
grep -rn "catch" . --include="*.ts" --include="*.js" -A 2 | grep -E 'return\s*(""|null|undefined|\[\])'

# Find missing additionalProperties: false
grep -rn '"type".*"object"' . --include="*.ts" --include="*.json" -A 10 | grep -v "additionalProperties"

# Find short tool descriptions
grep -rn "description:" . --include="*.ts" --include="*.js"

# Find tool_choice: "any" usage
grep -rn 'tool_choice.*"any"\|tool_choice.*'"'"'any'"'"'' . --include="*.ts" --include="*.js" --include="*.py"

# Find manual agentic loops
grep -rn "while.*true\|for.*;.*;" . --include="*.ts" --include="*.js" -A 5 | grep -E "query|stream|messages"

# Find context dumps to subagents
grep -rn "messages.*join\|conversation.*map.*query\|history.*stream" . --include="*.ts"

Pitfalls

Common mistakes to avoid when reviewing or building Claude agents:

• maxIterations with no StopHook — Setting maxIterations: 50 without a meaningful StopHook means the agent runs until budget is exhausted rather than completing a task. The guard and the exit condition must work together.
• stop_reason: "max_tokens" treated as success — When the model's response is truncated, stop_reason is "max_tokens" not "end_turn". Treating this as a successful completion produces silently truncated outputs. Always check stop_reason before acting on a response.
• Tool descriptions that are also parameter names — A tool named "search" with description "search" is meaningless. The description must explain when to use the tool, not what it is named.
• required: [] on tool schemas — An empty required array means all parameters are optional. The model will omit parameters it's unsure about and the tool silently gets undefined values. List every required parameter explicitly.
• Subagents inheriting maxIterations from parent — Subagents start a new Agent instance. They do not inherit the parent's iteration limit. Each must have its own maxIterations.
• StopHook reading stale state — If a StopHook checks a condition asynchronously (file exists, DB record updated), and the operation hasn't completed yet, it returns false and the agent keeps running. Ensure StopHook conditions are consistent reads, not eventually-consistent checks.
• MCP tools competing with native tools — When an MCP server exposes a tool with the same purpose as a native tool, the model alternates between them unpredictably. Ensure no overlap in tool semantics.

Verification

After a review or build session, confirm:

# 1. All Agent instantiations have maxIterations
grep -rn "new Agent(" . --include="*.ts" --include="*.js" | while read match; do
  file=$(echo "$match" | cut -d: -f1)
  line=$(echo "$match" | cut -d: -f2)
  end=$((line + 5))
  if ! sed -n "${line},${end}p" "$file" | grep -q "maxIterations"; then
    echo "MISSING maxIterations near: $match"
  fi
done
# Expected: no output

# 2. No silent catch blocks
grep -rn "catch" . --include="*.ts" --include="*.js" -A 3 | grep -E 'return\s*(""|\x27\x27|`{2}|\[\]|null|undefined)'
# Expected: no output

# 3. All object schemas have additionalProperties: false
grep -rn '"type".*"object"' . --include="*.ts" --include="*.json" -l | while read f; do
  grep -L "additionalProperties" "$f" && echo "MISSING additionalProperties: false in $f"
done
# Expected: no output

# 4. No tool description under 20 chars
grep -rn 'description.*:.*"' . --include="*.ts" --include="*.js" | awk -F'"' '{if(length($2) < 20 && length($2) > 0) print}'
# Expected: no output

# 5. Static scan clean
bash claude-agent-sdk-expert/scripts/scan-agent-patterns.sh . 2>&1 | grep "Patterns found"
# Expected: "Patterns found: 0"

References

#	Topic	File
0	Gotchas (Always Load)	references/gotchas.md
1	Agentic Loop Architecture	references/agentic-loop.md
2	Tool Design & Scoping	references/tool-design.md
3	Prompt Engineering	references/prompt-engineering.md
4	Structured Output	references/structured-output.md
5	Context Management	references/context-management.md
6	MCP Integration	references/mcp-integration.md
7	Error Handling	references/error-handling.md
8	Hooks & Lifecycle	references/hooks-lifecycle.md
9	Multi-Agent Patterns	references/multi-agent.md
10	Testing Agents	references/testing-agents.md
11	Observability	references/observability.md