OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add sammcj/agentic-coding --skill claude-agent-sdk
Use when working with Anthropic Claude Agent SDK. Provides architecture guidance, implementation patterns, best practices, and common pitfalls.
npx skills add sammcj/agentic-coding --skill claude-agent-sdk
The Claude Agent SDK enables building autonomous AI agents with Claude through a feedback loop architecture. Available for Python (3.10+) and TypeScript (Node 18+).
Repository:
Documentation: https://platform.claude.com/docs/en/agent-sdk/overview
Every agent follows this cycle:
This pattern applies whether you're building a simple script or a complex multi-agent system.
Choose mechanisms based on task requirements:
Rule: Use tools for repeatable operations, bash for exploration, code generation when you need structured output that can be validated.
In-process tools with no subprocess overhead. Primary building block for agents.
Python:
TypeScript:
Benefits over external MCP: Better performance, easier debugging, shared memory space, no IPC overhead.
Intercept and modify agent behaviour at specific points.
Available hooks:
PreToolUse → Validate/modify/deny tool calls before executionPostToolUse → Process/log/modify tool resultsStop → Handle completion eventsPython validation example:
TypeScript logging example:
Four modes with progressively less restriction:
default → Prompt for each tool useplan → Agent can read/explore freely, prompts for modificationsacceptEdits → Auto-approve file edits, prompt for bash/destructive opsbypassPermissions → Fully autonomous (use carefully)Dynamic control with canUseTool:
Isolated agents with separate context windows and specialised capabilities.
When to use:
Python:
TypeScript:
Agentic Search (Preferred): Use bash + filesystem navigation (grep, ls, tail) before reaching for semantic search. Simpler and more reliable.
Automatic Compaction: SDK automatically summarises messages when approaching token limits. Transparent and automatic.
Folder Structure as Context Engineering: Organise files intentionally—directory structure is visible to the agent and influences its understanding.
Explicit validation enables self-correction:
For UI tasks, screenshot and re-evaluate:
Only for fuzzy criteria where rules don't work (higher latency):
Symptom: CLAUDE.md ignored, custom prompts not applied
Solution: Set setting_sources=["project"] or ["user", "project"]
Symptom: "Tool not found" errors
Solution: Check MCP tool naming: mcp__{server_name}__{tool_name}
Symptom: Agent can't access directories Solution: Add directories explicitly:
Symptom: Syntax errors with async or continue parameters
Solution: Use async_ and continue_ (SDK auto-converts)
Symptom: Token limit errors Solution: Use subagents for isolation or let automatic compaction handle it
Symptom: Tools fail silently or with unclear errors Solution: Return structured error messages in tool responses:
Symptom: stdio/SSE MCP servers timeout Solution: Verify server is executable and logs are accessible:
| Aspect | Python | TypeScript |
|---|---|---|
| Runtime | anyio.run(main) | Native async/await |
| Min Version | Python 3.10+ | Node.js 18+ |
| Type Safety | Type hints optional | Strict types with Zod |
| Hook Fields | async_, continue_ | async, continue |
| CLI | Bundled (no install) | Separate install needed |
| Tool Validation | Dict-based schemas | Zod schemas |
✅ Use when:
❌ Don't use when:
Use Custom Tools when:
Use Bash when:
Use Code Generation when:
Use SDK MCP (in-process) when:
Use External MCP (stdio/SSE) when:
Python:
TypeScript:
Create alternative branches from a point:
Set USD spending limits:
Agent stops when budget exceeded. Useful for cost control in production.
Python:
TypeScript:
Test with real tools in isolated environment:
If migrating from the deprecated claude-code-sdk:
claude-code-sdk → claude-agent-sdksetting_sourcesClaudeCodeOptions → ClaudeAgentOptionssetting_sources=["project"]See migration guide: https://platform.claude.com/docs/en/agent-sdk/migration-guide
turn_limit parameter)add_dirs to limit scopeimport { ClaudeSdkClient } from '@anthropic-ai/agent-sdk';
const client = new ClaudeSdkClient({ apiKey: process.env.ANTHROPIC_API_KEY });
const result = await client.query({
model: 'claude-sonnet-4-5',
systemPrompt: 'You are a helpful coding assistant.',
userMessage: 'List files in current directory',
workingDir: '.',
});
console.log(result.finalMessage);from claude_agent_sdk.mcp import tool, create_sdk_mcp_server
@tool(
name="calculator",
description="Perform calculations",
input_schema={"expression": str}
)
async def calculator(args):
result = eval(args["expression"]) # Use safe eval in production
return {"content": [{"type": "text", "text": str(result)}]}
server = create_sdk_mcp_server(name="math", tools=[calculator])import { createSdkMcpServer, tool } from '@anthropic-ai/agent-sdk';
import { z } from 'zod';
const calculator = tool({
name: 'calculator',
description: 'Perform calculations',
inputSchema: z.object({ expression: z.string() }),
async execute({ expression }) {
const result = eval(expression); // Use safe eval in production
return { content: [{ type: 'text', text: String(result) }] };
},
});
const server = createSdkMcpServer({ name: 'math', tools: [calculator] });async def validate_command(input_data, tool_use_id, context):
if "rm -rf" in input_data["tool_input"].get("command", ""):
return {
"hookSpecificOutput": {
"permissionDecision": "deny",
"permissionDecisionReason": "Dangerous command blocked"
}
}const loggingHook = {
matcher: (input) => input.toolName === 'bash',
async handler(input, toolUseId, context) {
console.log(`Executing: ${input.toolInput.command}`);
}
};async def permission_callback(tool_name, tool_input, context):
if tool_name == "bash" and "git push" in tool_input.get("command", ""):
return False # Deny
return True # Allowfrom claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
subagent_definitions={
"researcher": {
"tools": ["read", "grep", "glob"],
"model": "claude-haiku-4",
"description": "Fast research agent"
}
}
)const options = {
subagentDefinitions: {
researcher: {
tools: ['read', 'grep', 'glob'],
model: 'claude-haiku-4',
description: 'Fast research agent'
}
}
};# In PostToolUse hook
if tool_name == "write":
# Run linter on generated file
lint_result = run_linter(tool_output)
if lint_result.has_errors:
return {"continue": True} # Let agent fix errors@tool(name="check_ui", description="Verify UI matches requirements")
async def check_ui(args):
screenshot = take_screenshot(args["url"])
# Return screenshot to agent for evaluation
return {"content": [{"type": "image", "source": screenshot}]}judge_result = await secondary_model.evaluate(
criteria="Does output match tone guidelines?",
output=agent_output
)# Python
options = ClaudeAgentOptions(setting_sources=["project"])
# TypeScript
const options = { settingSources: ['project'] };options = ClaudeAgentOptions(add_dirs=["/path/to/data"])# Use async_ not async
hook_result = {"async_": True, "continue_": False}return {
"content": [{
"type": "text",
"text": "Error: Invalid input. Expected format: ...",
"isError": True
}]
}# Check server stderr in context.mcp_server_logs
async def debug_hook(input_data, tool_use_id, context):
print(context.mcp_server_logs.get("server_name"))# First run
result1 = await query(user_message="Create a file", working_dir=".")
# Resume with new message
result2 = await query(
user_message="Now modify it",
working_dir=".",
session_id=result1.session_id
)// First run
const result1 = await client.query({ userMessage: 'Create a file' });
// Resume
const result2 = await client.query({
userMessage: 'Now modify it',
sessionId: result1.sessionId
});# Fork for different approach
result_fork = await query(
user_message="Try different implementation",
session_id=original_result.session_id,
fork_session=True
)options = ClaudeAgentOptions(budget={"usd": 5.00})import pytest
from unittest.mock import AsyncMock
@pytest.fixture
def mock_tool():
return AsyncMock(return_value={
"content": [{"type": "text", "text": "mocked"}]
})
async def test_agent(mock_tool):
server = create_sdk_mcp_server(name="test", tools=[mock_tool])
# Test with mocked toolimport { jest } from '@jest/globals';
const mockTool = {
name: 'test',
execute: jest.fn().mockResolvedValue({
content: [{ type: 'text', text: 'mocked' }]
})
};import tempfile
import os
async def test_file_operations():
with tempfile.TemporaryDirectory() as tmpdir:
result = await query(
user_message="Create test.txt with content 'hello'",
working_dir=tmpdir,
permission_mode="bypassPermissions"
)
assert os.path.exists(f"{tmpdir}/test.txt")