**Status**: Production Ready
/plugin marketplace add secondsky/claude-skills/plugin install claude-agent-sdk@claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/mcp-servers-guide.mdreferences/permissions-guide.mdreferences/query-api-reference.mdreferences/session-management.mdreferences/subagents-patterns.mdreferences/top-errors.mdscripts/check-versions.shtemplates/basic-query.tstemplates/custom-mcp-server.tstemplates/error-handling.tstemplates/filesystem-settings.tstemplates/multi-agent-workflow.tstemplates/package.jsontemplates/permission-control.tstemplates/query-with-tools.tstemplates/session-management.tstemplates/subagents-orchestration.tstemplates/tsconfig.jsonStatus: Production Ready Last Updated: 2025-11-21 Dependencies: @anthropic-ai/claude-code, zod Latest Versions: @anthropic-ai/claude-code@2.0.49+, zod@3.23.0+
bun add @anthropic-ai/claude-agent-sdk zod
Why these packages:
@anthropic-ai/claude-agent-sdk - Main Agent SDKzod - Type-safe schema validation for toolsexport ANTHROPIC_API_KEY="sk-ant-..."
CRITICAL:
import { query } from "@anthropic-ai/claude-agent-sdk";
const response = query({
prompt: "Analyze the codebase and suggest improvements",
options: {
model: "claude-sonnet-4-5",
workingDirectory: process.cwd(),
allowedTools: ["Read", "Grep", "Glob"]
}
});
for await (const message of response) {
if (message.type === 'assistant') {
console.log(message.content);
}
}
The skill includes comprehensive reference files for deep dives. Load these when needed:
references/query-api-reference.md - Load when configuring query() options, working with message types, understanding filesystem settings, or debugging API behaviorreferences/mcp-servers-guide.md - Load when creating custom tools, integrating external MCP servers, or debugging server connectionsreferences/subagents-patterns.md - Load when designing multi-agent systems, orchestrating specialized agents, or optimizing agent workflowsreferences/session-management.md - Load when implementing persistent conversations, forking sessions, or managing long-running interactionsreferences/permissions-guide.md - Load when implementing custom permission logic, securing agent capabilities, or controlling tool accessreferences/top-errors.md - Load when encountering errors, debugging issues, or implementing error handlingThe query() function is the primary interface for interacting with Claude Code CLI programmatically. It returns an AsyncGenerator that streams messages as the agent works.
For complete API details, options, and advanced patterns: Load references/query-api-reference.md when working with advanced configurations, message streaming, or filesystem settings.
import { query } from "@anthropic-ai/claude-agent-sdk";
const response = query({
prompt: "Review this code for bugs",
options: {
model: "claude-sonnet-4-5", // or "haiku", "opus"
workingDirectory: "/path/to/project",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "default"
}
});
for await (const message of response) {
// Process streaming messages
}
| Model | ID | Best For | Speed | Capability |
|---|---|---|---|---|
| Haiku | "haiku" | Fast tasks, monitoring | Fastest | Basic |
| Sonnet | "sonnet" or "claude-sonnet-4-5" | Balanced | Medium | High |
| Opus | "opus" | Complex reasoning | Slowest | Highest |
Claude Code provides built-in tools (Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, Task) that can be controlled via allowedTools and disallowedTools options.
For complete tool configuration, custom monitoring, and advanced patterns: Load references/query-api-reference.md when implementing tool restrictions or monitoring.
// Whitelist approach (recommended)
const response = query({
prompt: "Analyze code but don't modify anything",
options: {
allowedTools: ["Read", "Grep", "Glob"]
// ONLY these tools can be used
}
});
// Blacklist approach
const response = query({
prompt: "Review and fix issues",
options: {
disallowedTools: ["Bash"]
// Everything except Bash allowed
}
});
CRITICAL: allowedTools = whitelist (only these tools), disallowedTools = blacklist (everything except these). If both specified, allowedTools wins.
MCP servers extend agent capabilities with custom tools via createSdkMcpServer() (in-process) or external servers (stdio, HTTP, SSE).
For complete MCP server implementation guide: Load references/mcp-servers-guide.md when creating custom tools or integrating MCP servers.
Quick Example: Create server with tool(name, description, zodSchema, handler), use with mcpServers option and allowedTools: ["mcp__<server>__<tool>"]
Specialized agents with focused expertise, custom tools, different models, and dedicated prompts for multi-agent workflows.
For complete subagent patterns and orchestration strategies: Load references/subagents-patterns.md when designing multi-agent systems.
AgentDefinition: Use agents option with objects containing description, prompt, tools (optional), model (optional)
Sessions enable persistent conversations, context preservation, and alternative exploration paths (forking).
For complete session patterns and workflows: Load references/session-management.md when implementing persistent conversations.
Usage: Capture session_id from system init message, resume with resume: sessionId option, fork with forkSession: true
Control agent capabilities with permission modes: "default" (standard checks), "acceptEdits" (auto-approve edits), "bypassPermissions" (skip all checks - use with caution).
For complete permission patterns and security policies: Load references/permissions-guide.md when implementing custom permission logic.
Custom Logic: Use canUseTool: async (toolName, input) => ({ behavior: "allow" | "deny" | "ask", message?: string }) callback
Control which settings files load via settingSources array: "user" (~/.claude/settings.json), "project" (.claude/settings.json), "local" (.claude/settings.local.json).
For complete configuration and priority rules: Load references/query-api-reference.md when configuring settings sources.
Default: [] (no settings loaded). Priority: Programmatic > local > project > user
The SDK streams messages: system (init/completion), assistant (responses), tool_call (tool requests), tool_result (tool outputs), error (failures).
For complete message type reference and streaming patterns: Load references/query-api-reference.md when implementing advanced message handling.
Usage: Process messages in for await (const message of response) loop, switch on message.type
Common errors: CLI_NOT_FOUND, AUTHENTICATION_FAILED, RATE_LIMIT_EXCEEDED, CONTEXT_LENGTH_EXCEEDED, PERMISSION_DENIED.
For complete error catalog with solutions: Load references/top-errors.md when encountering errors or implementing error handling.
Pattern: Wrap query in try/catch, check error.code, handle message.type === 'error' in streaming loop
This skill prevents 12 documented issues. The top 3 most common:
Error: "Claude Code CLI not installed"
Prevention: Install before using SDK: bun add -g @anthropic-ai/claude-code
Error: "Invalid API key"
Prevention: Always set export ANTHROPIC_API_KEY="sk-ant-..."
Error: Tool execution blocked
Prevention: Use allowedTools or custom canUseTool callback
For all 12 errors with complete solutions: Load references/top-errors.md when debugging or implementing error prevention.
✅ Install Claude Code CLI before using SDK
✅ Set ANTHROPIC_API_KEY environment variable
✅ Capture session_id from system messages for resuming
✅ Use allowedTools to restrict agent capabilities
✅ Implement canUseTool for custom permission logic
✅ Handle all message types in streaming loop
✅ Use Zod schemas for tool input validation
✅ Set workingDirectory for multi-project environments
✅ Test MCP servers in isolation before integration
✅ Use settingSources: ["project"] in CI/CD
✅ Monitor tool execution with tool_call messages
✅ Implement error handling for all queries
❌ Commit API keys to version control
❌ Use bypassPermissions in production (unless sandboxed)
❌ Assume tools executed (check tool_result messages)
❌ Ignore error messages in stream
❌ Skip session ID capture if planning to resume
❌ Use duplicate tool names across MCP servers
❌ Allow unrestricted Bash access without canUseTool
❌ Load settings from user in CI/CD (settingSources: ["user"])
❌ Trust tool results without validation
❌ Hardcode file paths (use workingDirectory)
❌ Use acceptEdits mode with untrusted prompts
❌ Skip Zod validation for tool inputs
Required:
@anthropic-ai/claude-agent-sdk@0.1.0+ - Agent SDKzod@3.23.0+ - Schema validationOptional:
@types/node@20.0.0+ - TypeScript types@modelcontextprotocol/sdk@latest - MCP server developmentSystem Requirements:
bun add -g @anthropic-ai/claude-code){
"dependencies": {
"@anthropic-ai/claude-agent-sdk": "^0.1.0",
"zod": "^3.23.0"
},
"devDependencies": {
"@types/node": "^20.0.0",
"typescript": "^5.3.0"
}
}
This skill is based on official Anthropic documentation and SDK patterns:
bun add -g @anthropic-ai/claude-code)bun add @anthropic-ai/claude-agent-sdk zod)Questions? Issues?
Token Efficiency: ~65% savings vs manual Agent SDK integration (estimated) Error Prevention: 100% (all 12 documented issues prevented) Development Time: 30 minutes with skill vs 3-4 hours manual
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.