--- id: Mathews-Tom/armory/agent-builder version: "031da035" license: MIT install: manual updated: 2026-07-21 --- # agent-builder — Agent Builder guides you through creating AI agents using the Claude Agent SDK and headless mode—no raw API keys needed. Build custom tools with MCP servers, control execution with hooks, and deploy agents in Python or via CLI commands. Covers SDK patterns, security practices, and production workflows. Publisher: Mathews-Tom · Stars: 274 · Updated: 2026-07-21 Install (manual): `git clone https://github.com/Mathews-Tom/armory` ## SKILL.md # 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. ```text 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 1. **Claude Agent SDK Python** - Programmatic agent creation with custom tools and hooks (wraps Claude Code CLI) 2. **Headless/Print Mode** - Run Claude Code from CLI, scripts, CI/CD (`claude -p`) 3. **CLI Reference** - All commands, flags, and configuration options **All use Claude Code's existing authentication from `~/.claude/` — no API keys required.** --- ## Documentation Sources - **Agent SDK**: https://github.com/anthropics/claude-agent-sdk-python - **Headless Mode**: https://code.claude.com/docs/en/headless - **CLI Reference**: https://code.claude.com/docs/en/cli-reference --- ## Workflow 1. **Understand the requirement** - What type of agent/automation is needed? 2. **Check dependencies** - Verify Python version, packages, Claude Code installation 3. **Reference live docs** - Fetch relevant documentation if details are unclear 4. **Build confidently** - Write production-ready code with proper error handling 5. **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: - [ ] **Verify:** Using Claude Code headless mode (`claude -p` or `claude_agent_sdk`) — not raw Anthropic API - [ ] **Verify:** No API keys in code — authentication comes from `~/.claude/` config - [ ] Confirm Python version (3.10+) - [ ] Verify Claude Code CLI installation (`which claude`) - [ ] Check required packages with `uv pip list` - [ ] Understand the specific use case - [ ] Determine if SDK or CLI approach is needed After writing code: - [ ] **Verify:** Code uses `claude_agent_sdk` or `claude -p` — not `anthropic.Anthropic()` - [ ] **Verify:** No `ANTHROPIC_API_KEY` or `api_key=` parameters in code - [ ] Add error handling for all SDK exceptions - [ ] Test with actual Claude Code installation - [ ] Validate tool permissions and security - [ ] Set appropriate limits (turns, budget) - [ ] Document custom tools and their purposes --- ## 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. [View on SkillFed](https://skillfed.io/Mathews-Tom/armory/agent-builder) · [View on GitHub](https://github.com/Mathews-Tom/armory)