claude-agent-sdk_skill

Overview

This skill is a practical guide to the Claude Agent SDK for building autonomous AI agents that read and edit files, run shell commands, manage sessions, and integrate custom tools. It focuses on concrete workflows, permission controls, file checkpointing, and production readiness for agents working with codebases and file systems.

How this skill works

The SDK exposes a one-shot query API and a session-based client that preserves context across turns. It provides built-in tools (Read, Write, Edit, Bash, Grep), decorators to register custom MCP tools, and options to control allowed/disallowed tools, permission handling, and file checkpointing. Agents operate by issuing queries and receiving streamed messages; tools are invoked by the agent and validated by configurable permission handlers.

When to use it

• Building autonomous agents that need to read, modify, or create files in a repository
• Creating agents that must run shell commands or analyze a codebase
• Integrating custom services or domain-specific tools via MCP servers
• Managing multi-turn conversations where context and session state matter
• Enforcing tool permission rules and sandboxing sensitive operations
• Implementing file checkpointing and rewind for safe iterative edits

Best practices

• Whitelist only the tools the agent needs using allowed_tools; blacklist destructive tools via disallowed_tools
• Implement a custom permission handler to block or sanitize file paths and sensitive operations
• Enable file checkpointing for workflows that edit files so you can rewind changes on error
• Use ClaudeSDKClient for multi-turn sessions and query() for simple one-shot tasks
• Run agents within a controlled working directory (cwd) and inject minimal required env vars
• Log tool invocations and session activity for monitoring and debugging in production

Example use cases

• Code analysis agent that scans a project with Read and Grep to produce an architecture summary
• Refactor agent that edits multiple files with Write/Edit and uses checkpointing to revert if needed
• Automation agent that runs build or test commands via Bash and reports results
• Custom calculator or translation service exposed as MCP tools and consumed by agents
• Session-based assistant that remembers prior queries and continues a long-running debugging workflow