claude-agent-sdk

What it does

The skill describes using the Claude Agent SDK to build autonomous AI agents with structured outputs that validate against JSON schemas. It emphasizes an outputFormat mechanism, type safety with Zod, and a plugins system plus hooks for event-driven workflows. It also notes prevention of 14 documented errors and outlines use cases such as building coding agents, SRE systems, security auditors, and troubleshooting CLI not found or MCP config issues.

How it works

The Core API is query(prompt, options) returning an async generator of messages. Key elements include:

• outputFormat: enables structured JSON schema validation and defines the output structure.
• settingSources, canUseTool, agents, mcpServers, permissionMode, betas, sandbox, enableFileCheckpointing, systemPrompt: critical options for configuration.
• System prompts can be simple strings or preset forms, with a preset that includes Claude Code defaults.
• Built-in tools include a variety of utilities (Read, Write, Edit, Bash, etc.), with optional tool control via allowedTools, disallowedTools, and canUseTool callback for dynamic permission logic.
• Plugins and Hooks (12 Hook Events) allow customizing behavior around tool calls, session management, and errors. Hook examples show PreToolUse and PostToolUse usage and a Stop hook for cleanup.
• Subagent orchestration and MCP servers enable subagent definitions and external server configurations for modular tool usage.

When to use it

Use when building agents that require structured, validated outputs, robust error handling, and hook-driven workflows, particularly for security-conscious or tooling-heavy tasks, including coding agents, SRE systems, security auditors, or troubleshooting CLI not found, MCP config issues, and subagent cleanup. Triggers include feature availability like structured outputs and hooks, and the need for strict MCP/config validation.

What it can touch

The skill references:

• Tools: built-in tools such as Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, Task, NotebookEdit, BashOutput, KillBash, ListMcpResources, ReadMcpResource, AskUserQuestion.
• Hook system: PreToolUse, PostToolUse, Notification, UserPromptSubmit, SubagentStart, SubagentStop, PreCompact, PermissionRequest, Stop, SessionStart, SessionEnd, Error.
• MCP Servers (External, both stdio and HTTP/SSE) with tool definitions via tool(name, description, zodSchema, handler).
• Subagent definitions via AgentDefinition including description, prompt, tools, model, skills, maxTurns.
• Session management options like resume, forkSession, continue, and V2 session APIs.

Caveats

The guide mentions known subagent cleanup issues where subagents may continue running after the parent stops and suggests Stop hook cleanup as a workaround. It also notes that subagent cleanup behavior is under discussion (Issue references) and that V2 APIs exist in preview with unstable naming. License is MIT, and the skill is categorized under Security with declared tool claude-code.