Agent Builder - Claude SDK & CLI Expert
Triggers:
- "build agent", "create agent", "agent sdk", "claude sdk"
- "headless mode", "programmatic", "cli command"
- "claude -p", "query programmatically"
- "custom tools", "mcp server", "sdk mcp"
- "claude code api", "agent options"
Prefer Claude Code Headless Mode
This skill covers Claude Code's headless mode and the Agent SDK — not the raw Anthropic API.
Preferred: Claude Code CLI headless mode (claude -p)
Preferred: Claude Agent SDK (wraps Claude Code CLI)
Avoid: Raw Anthropic API (anthropic.Anthropic())
Avoid: Direct API calls with API keys
Why this matters:
- The Agent SDK wraps the Claude Code CLI — it does not use the raw Anthropic API
- Authentication comes from existing
~/.claude/ config — no API keys needed
- All settings, MCP servers, and configuration inherit from your Claude Code setup
- You get Claude Code's full agent loop, tools, and context management
Rule: If code uses anthropic.Anthropic(), anthropic.messages.create(), or requires ANTHROPIC_API_KEY, that is the wrong approach. Use claude -p or claude_agent_sdk instead.
Core Capabilities
- Claude Agent SDK Python - Programmatic agent creation with custom tools and hooks (wraps Claude Code CLI)
- Headless/Print Mode - Run Claude Code from CLI, scripts, CI/CD (
claude -p)
- CLI Reference - All commands, flags, and configuration options
All use Claude Code's existing authentication from ~/.claude/ — no API keys required.
Documentation Sources
Workflow
- Understand the requirement - What type of agent/automation is needed?
- Check dependencies - Verify Python version, packages, Claude Code installation
- Reference live docs - Fetch relevant documentation if details are unclear
- Build confidently - Write production-ready code with proper error handling
- Test immediately - Run and validate the implementation
Reference Files
Load only the reference file relevant to the current task.
| Task |
Load |
| Distinguishing raw Anthropic API from Claude Code SDK patterns |
references/api-vs-sdk.md |
| Writing a Python agent with the Agent SDK (install, query, client, tools, hooks, errors) |
references/sdk-python.md |
Using headless claude -p mode (basic, JSON schema, streaming, tool approval, sessions, system prompts) |
references/headless-cli.md |
| CLI commands, flags table, dynamic subagents, permission rule syntax |
references/cli-reference.md |
| Use-case templates: CI/CD pipeline, code review, custom analysis tool, database query agent |
references/use-cases.md |
| Agent SDK and CLI/Headless best practices |
references/best-practices.md |
| Complete end-to-end agent example (tools + hooks + client) |
references/example-agent.md |
| Output format conventions for produced artifacts |
references/output-format.md |
Security
- Do not use
--dangerously-skip-permissions in production
- Validate inputs in custom tools
- Use permission rules to block destructive commands
- Set budget limits with
--max-budget-usd
- Implement hooks for sensitive operations
- Review allowed tools before automation
Quick Decision Tree
Need to...
- Run one-off query →
claude -p "query"
- Build custom agent → Agent SDK with
ClaudeSDKClient
- Add custom tools → SDK MCP server with
@tool decorator
- Control execution → Hooks with
HookMatcher
- Stream responses →
--output-format stream-json
- Get structured data →
--json-schema
- Continue conversation →
--continue or --resume
- Run in CI/CD →
claude -p with --allowedTools
- Integrate with app → Python SDK with
query() or ClaudeSDKClient
When to Fetch Docs
Fetch live documentation when:
- API signatures or parameters are unclear
- New features or flags are mentioned
- Error messages reference unknown configuration
- Implementing complex hooks or MCP servers
- User asks about specific capabilities
Use WebFetch tool to pull latest documentation from source URLs.
Implementation Checklist
Before writing code:
After writing code:
Skill Invocation
This skill provides:
- Complete Agent SDK implementation guidance
- Headless/CLI command construction
- Custom tool creation with MCP servers
- Hook implementation for control flow
- Security best practices
- Live documentation fetching when needed
Ask specific questions about building agents, running headless commands, or CLI usage.
Limitations
- The Agent SDK is Python-only (Python 3.10+); no JavaScript or other language bindings are covered here.
- Requires Claude Code CLI installed and authenticated via
~/.claude/ before any SDK or headless usage works.
- This skill does not cover raw Anthropic API usage (
anthropic.Anthropic()); see the Anthropic API docs for that.
- Agent processes launched via the SDK are ephemeral by default; session persistence requires explicit
--resume or session ID capture.
- MCP server patterns in this skill use stdio transport; HTTP-based MCP transports require separate configuration not covered here.
1---2name: agent-builder3description: Build AI agents and automate Claude Code programmatically via the Claude Agent SDK and headless CLI mode. Covers Python SDK, claude -p, SDK MCP servers, hooks, sessions. Triggers on: "build an agent", "agent SDK", "headless mode", "automate Claude", "programmatic agent".4---56# Agent Builder - Claude SDK & CLI Expert78**Triggers:**910- "build agent", "create agent", "agent sdk", "claude sdk"11- "headless mode", "programmatic", "cli command"12- "claude -p", "query programmatically"13- "custom tools", "mcp server", "sdk mcp"14- "claude code api", "agent options"1516---1718## Prefer Claude Code Headless Mode1920This skill covers Claude Code's headless mode and the Agent SDK — not the raw Anthropic API.2122```text23Preferred: Claude Code CLI headless mode (claude -p)24Preferred: Claude Agent SDK (wraps Claude Code CLI)25Avoid: Raw Anthropic API (anthropic.Anthropic())26Avoid: Direct API calls with API keys27```2829**Why this matters:**3031- The Agent SDK wraps the Claude Code CLI — it does not use the raw Anthropic API32- Authentication comes from existing `~/.claude/` config — no API keys needed33- All settings, MCP servers, and configuration inherit from your Claude Code setup34- You get Claude Code's full agent loop, tools, and context management3536**Rule:** If code uses `anthropic.Anthropic()`, `anthropic.messages.create()`, or requires `ANTHROPIC_API_KEY`, that is the wrong approach. Use `claude -p` or `claude_agent_sdk` instead.3738---3940## Core Capabilities41421. **Claude Agent SDK Python** - Programmatic agent creation with custom tools and hooks (wraps Claude Code CLI)432. **Headless/Print Mode** - Run Claude Code from CLI, scripts, CI/CD (`claude -p`)443. **CLI Reference** - All commands, flags, and configuration options4546**All use Claude Code's existing authentication from `~/.claude/` — no API keys required.**4748---4950## Documentation Sources5152- **Agent SDK**: https://github.com/anthropics/claude-agent-sdk-python53- **Headless Mode**: https://code.claude.com/docs/en/headless54- **CLI Reference**: https://code.claude.com/docs/en/cli-reference5556---5758## Workflow59601. **Understand the requirement** - What type of agent/automation is needed?612. **Check dependencies** - Verify Python version, packages, Claude Code installation623. **Reference live docs** - Fetch relevant documentation if details are unclear634. **Build confidently** - Write production-ready code with proper error handling645. **Test immediately** - Run and validate the implementation6566---6768## Reference Files6970Load only the reference file relevant to the current task.7172| Task | Load |73|---|---|74| Distinguishing raw Anthropic API from Claude Code SDK patterns | `references/api-vs-sdk.md` |75| Writing a Python agent with the Agent SDK (install, query, client, tools, hooks, errors) | `references/sdk-python.md` |76| Using headless `claude -p` mode (basic, JSON schema, streaming, tool approval, sessions, system prompts) | `references/headless-cli.md` |77| CLI commands, flags table, dynamic subagents, permission rule syntax | `references/cli-reference.md` |78| Use-case templates: CI/CD pipeline, code review, custom analysis tool, database query agent | `references/use-cases.md` |79| Agent SDK and CLI/Headless best practices | `references/best-practices.md` |80| Complete end-to-end agent example (tools + hooks + client) | `references/example-agent.md` |81| Output format conventions for produced artifacts | `references/output-format.md` |8283---8485## Security8687- Do not use `--dangerously-skip-permissions` in production88- Validate inputs in custom tools89- Use permission rules to block destructive commands90- Set budget limits with `--max-budget-usd`91- Implement hooks for sensitive operations92- Review allowed tools before automation9394---9596## Quick Decision Tree9798**Need to...**99100- Run one-off query → `claude -p "query"`101- Build custom agent → Agent SDK with `ClaudeSDKClient`102- Add custom tools → SDK MCP server with `@tool` decorator103- Control execution → Hooks with `HookMatcher`104- Stream responses → `--output-format stream-json`105- Get structured data → `--json-schema`106- Continue conversation → `--continue` or `--resume`107- Run in CI/CD → `claude -p` with `--allowedTools`108- Integrate with app → Python SDK with `query()` or `ClaudeSDKClient`109110---111112## When to Fetch Docs113114Fetch live documentation when:115116- API signatures or parameters are unclear117- New features or flags are mentioned118- Error messages reference unknown configuration119- Implementing complex hooks or MCP servers120- User asks about specific capabilities121122Use `WebFetch` tool to pull latest documentation from source URLs.123124---125126## Implementation Checklist127128Before writing code:129130- [ ] **Verify:** Using Claude Code headless mode (`claude -p` or `claude_agent_sdk`) — not raw Anthropic API131- [ ] **Verify:** No API keys in code — authentication comes from `~/.claude/` config132- [ ] Confirm Python version (3.10+)133- [ ] Verify Claude Code CLI installation (`which claude`)134- [ ] Check required packages with `uv pip list`135- [ ] Understand the specific use case136- [ ] Determine if SDK or CLI approach is needed137138After writing code:139140- [ ] **Verify:** Code uses `claude_agent_sdk` or `claude -p` — not `anthropic.Anthropic()`141- [ ] **Verify:** No `ANTHROPIC_API_KEY` or `api_key=` parameters in code142- [ ] Add error handling for all SDK exceptions143- [ ] Test with actual Claude Code installation144- [ ] Validate tool permissions and security145- [ ] Set appropriate limits (turns, budget)146- [ ] Document custom tools and their purposes147148---149150## Skill Invocation151152This skill provides:153154- Complete Agent SDK implementation guidance155- Headless/CLI command construction156- Custom tool creation with MCP servers157- Hook implementation for control flow158- Security best practices159- Live documentation fetching when needed160161Ask specific questions about building agents, running headless commands, or CLI usage.162163---164165## Limitations166167- The Agent SDK is Python-only (Python 3.10+); no JavaScript or other language bindings are covered here.168- Requires Claude Code CLI installed and authenticated via `~/.claude/` before any SDK or headless usage works.169- This skill does not cover raw Anthropic API usage (`anthropic.Anthropic()`); see the Anthropic API docs for that.170- Agent processes launched via the SDK are ephemeral by default; session persistence requires explicit `--resume` or session ID capture.171- MCP server patterns in this skill use stdio transport; HTTP-based MCP transports require separate configuration not covered here.
mathews-tom