Agent Squad Python Guide
2FastLabs/agent-squad
Map of the agent-squad Python framework for async multi-agent orchestration: which agent, classifier, storage and tool provider to pick, and the pitfalls to avoid.
Build AI agents and automate Claude Code programmatically via the Claude Agent SDK and headless CLI mode.
Install Agent Builder
$ npx skills add Mathews-Tom/armory --skill agent-builder -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install Mathews-Tom/armory agent-builder --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/agent-builder .claude/skills/agent-builder && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "agent-builder" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/agent-builder into .claude/skills/agent-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "agent-builder", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/Mathews-Tom/armory/tree/main/skills/agent-builderType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add Mathews-Tom/armory --skill agent-builder -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install Mathews-Tom/armory agent-builder --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/agent-builder .agents/skills/agent-builder && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "agent-builder" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/agent-builder into .agents/skills/agent-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "agent-builder", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add Mathews-Tom/armory --skill agent-builder -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install Mathews-Tom/armory agent-builder --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/agent-builder .cursor/skills/agent-builder && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "agent-builder" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/agent-builder into .cursor/skills/agent-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "agent-builder", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/Mathews-Tom/armory.git --path skills/agent-builder--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add Mathews-Tom/armory --skill agent-builder -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install Mathews-Tom/armory agent-builder --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/agent-builder .gemini/skills/agent-builder && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "agent-builder" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/agent-builder into .gemini/skills/agent-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "agent-builder", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install Mathews-Tom/armory agent-builderInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add Mathews-Tom/armory --skill agent-builder -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/agent-builder .github/skills/agent-builder && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "agent-builder" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/agent-builder into .github/skills/agent-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "agent-builder", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add Mathews-Tom/armory --skill agent-builder -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install Mathews-Tom/armory agent-builder --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Mathews-Tom/armory.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/agent-builder .opencode/skills/agent-builder && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "agent-builder" agent skill from https://github.com/Mathews-Tom/armory/tree/main/skills/agent-builder into .opencode/skills/agent-builder/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "agent-builder", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
agent-builder- GitHub stars
- 327
- Token cost
- ~1.7k tokens
- SKILL.md length
- 722 words
- Files
- 10 (incl. references)
- Skills in repo
- 80
- Repo updated
- First seen
- Licence
- MIT
At a glance
Build AI agents and automate Claude Code programmatically via the Claude Agent SDK and headless CLI mode.
- Works in 3 steps: Claude Agent SDK Python - Programmatic… → Headless/Print Mode - Run Claude Code… → CLI Reference - All commands, flags, and…
- : build an agent
- SKILL.md covers Prefer Claude Code Headless Mode, Core Capabilities, Documentation Sources and Workflow, plus 7 more sections
- Calls claude and uv; needs ANTHROPIC_API_KEY
What it does
Agent Builder is an agent skill from Mathews-Tom/armory. 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".
Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 11 other files, including reference files (for example `evals/cases.yaml`, `references/api-vs-sdk.md` and `references/best-practices.md`).
It sits in AI & LLM Engineering, covering Building AI agents. It works with Model Context Protocol, Claude Agent SDK, Python and Anthropic API. The repository describes itself as: Curated, production-grade skills for AI coding agents. Battle-tested workflows for developers who use AI seriously. The licence is MIT.
When your agent uses it
- : build an agent
- Automate Claude
- Programmatic agent
Example prompts
- “build an agent”
- “agent SDK”
- “headless mode”
- “/agent-builder”
Requirements
- Python 3
- A credential in ANTHROPIC_API_KEY
Workflow steps
3 steps, taken from the first numbered list in SKILL.md.
- 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
What it can do on your machine
Read from SKILL.md and the folder at commit 4594fb7. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
claudeuv
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
code.claude.comgithub.com
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names these keys or tokens, usually read from environment variables:
ANTHROPIC_API_KEY
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Agent Builder loads about 1.7k tokens when it runs, and up to ~5.6k if it reads all its reference files. Until then it costs about 71 tokens; SKILL.md has 722 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from Mathews-Tom/armory at commit 4594fb7, republished under its MIT licence (© Mathews-Tom). 722 words, ~1,663 tokens.
Download SKILL.mdSave it as
.claude/skills/agent-builder/SKILL.md (or your agent's skills folder). This skill also uses 9 other files; get the full folder from GitHub.- name
- agent-builder
- description
- 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".
- metadata.version
- 1.1.1
- metadata.category
- development
- metadata.tags
- agent-sdk, headless, automation, mcp
- metadata.difficulty
- intermediate
- metadata.phase
- build
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 keysWhy 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
- 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
- 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-permissionsin 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
@tooldecorator - Control execution → Hooks with
HookMatcher - Stream responses →
--output-format stream-json - Get structured data →
--json-schema - Continue conversation →
--continueor--resume - Run in CI/CD →
claude -pwith--allowedTools - Integrate with app → Python SDK with
query()orClaudeSDKClient
Show full SKILL.md (287 more words)Show less
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 -porclaude_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_sdkorclaude -p— notanthropic.Anthropic() - Verify: No
ANTHROPIC_API_KEYorapi_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
--resumeor session ID capture. - MCP server patterns in this skill use stdio transport; HTTP-based MCP transports require separate configuration not covered here.
© Mathews-Tom, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 9 other files (references) in skills/agent-builder of Mathews-Tom/armory.
- SKILL.md
- evals/cases.yaml
- references/api-vs-sdk.md
- references/best-practices.md
- references/cli-reference.md
- references/example-agent.md
- references/headless-cli.md
- references/output-format.md
- references/sdk-python.md
- references/use-cases.md
Open the folder on GitHubat commit 4594fb7
Compare with similar skills
Agent Builder next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Agent Builder this skillMathews-Tom/armory | 327 | — | ~1.7k | Automated safety check: Pass | MIT | |
| Agent Squad Python Guide2FastLabs/agent-squad | 7.8k | — | ~4.7k | Automated safety check: Pass | Apache-2.0 | |
| Compact Memory Implementationsimbajigege/book2skills | 184 | — | ~2.5k | Automated safety check: Pass | MIT | |
| Strandsstrands-agents/harness-sdk | 8.7k | — | ~1k | Automated safety check: Pass | Apache-2.0 | |
| Cc GuidemikeOnBreeze/cc-crossbeam | 293 | — | ~668 | Automated safety check: Pass | MIT | |
| Claude Agent SDKsammcj/agentic-coding | 162 | — | ~3.8k | Automated safety check: Pass | Apache-2.0 |
Similar skills
Compact Memory Implementation
simbajigege/book2skills
A developer guide to adding compact memory to an agent: when to trigger compaction, how to fork a compactor sub-agent, what the summary holds, and how to restore it.
Strands
strands-agents/harness-sdk
Build, extend, evaluate, or migrate applications with Strands Agents in Python or TypeScript.
Cc Guide
mikeOnBreeze/cc-crossbeam
Claude Code documentation expert. An agent skill from mikeOnBreeze/cc-crossbeam.
Claude Agent SDK
sammcj/agentic-coding
A skill your agent uses when working with Anthropic Claude Agent SDK.
Ydc Openai Agent SDK Integration
LeoYeAI/openclaw-master-skills
Integrate OpenAI Agents SDK with You.com MCP server - Hosted and Streamable HTTP support for Python and TypeScript.
More from Mathews-Tom/armory
All 80 skills in this repoArchitecture Reviewer
Mathews-Tom/armory
Architecture reviews across 7 dimensions (structural, scalability, enterprise readiness, performance, security, ops, data) with scored reports.
Concept To Image
Mathews-Tom/armory
Turn concepts into static HTML visuals exported as PNG or SVG files via HTML/CSS/SVG.
Watch
Mathews-Tom/armory
A skill your agent uses when analyzing an existing video URL or local recording: "watch this video", "analyze youtube video", "summarize this video", "youtube transcript", "find this moment", "what…
Code Refiner
Mathews-Tom/armory
Deep code simplification and refactoring preserving behavior across Python, Go, TypeScript, Rust.
Concept To Video
Mathews-Tom/armory
Turn concepts into animated explainer videos using Manim (Python) with MP4/GIF output, audio overlay, multi-scene composition.
Decision Map
Mathews-Tom/armory
Maps the unresolved architecture, policy, and scope decisions that must be answered before planning can start: one durable decision ticket per question on the issue tracker, typed and blocker-linked…
Related
Categories
Questions about Agent Builder
What does Agent Builder do?
Build AI agents and automate Claude Code programmatically via the Claude Agent SDK and headless CLI mode. Agent Builder is an agent skill from Mathews-Tom/armory. Build AI agents and automate Claude Code programmatically via the Claude Agent SDK and headless CLI mode.
When should I use Agent Builder?
Agent Builder fits situations like: : build an agent; automate Claude; programmatic agent.
How do I install Agent Builder in Claude Code?
Run `npx skills add Mathews-Tom/armory --skill agent-builder -a claude-code`. Or copy the skill folder (skills/agent-builder in Mathews-Tom/armory) into .claude/skills/agent-builder in your project. Claude Code loads it when a task matches its description.
How do I install Agent Builder in Codex?
Run `npx skills add Mathews-Tom/armory --skill agent-builder -a codex`. Or copy the skill folder (skills/agent-builder in Mathews-Tom/armory) into .agents/skills/agent-builder in your project. Codex loads it when a task matches its description.
Can I use Agent Builder in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Mathews-Tom/armory --skill agent-builder -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/agent-builder, .gemini/skills/agent-builder, .github/skills/agent-builder and .opencode/skills/agent-builder in your project.
What does Agent Builder need to run?
Going by SKILL.md and its folder, Agent Builder needs the command-line tools its instructions call (claude and uv) and credentials named ANTHROPIC_API_KEY. Our summary lists: Python 3; A credential in ANTHROPIC_API_KEY.
Does Agent Builder access the network?
SKILL.md names 2 domains. As links in the text: code.claude.com and github.com. This is read from the text; nothing was executed.
Is Agent Builder safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Agent Builder use?
Agent Builder is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Agent Builder use?
About 1.7k tokens (SKILL.md is roughly 6.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 3.9k tokens, read only when the agent opens those files.
What are the alternatives to Agent Builder?
Skills that share tags, products or a category with Agent Builder: Agent Squad Python Guide (2FastLabs/agent-squad, 7.8k stars), Compact Memory Implementation (simbajigege/book2skills, 184 stars), Strands (strands-agents/harness-sdk, 8.7k stars) and Cc Guide (mikeOnBreeze/cc-crossbeam, 293 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Agent Builder?
Mathews-Tom (a GitHub user) maintains it in Mathews-Tom/armory, which has 327 GitHub stars. The repository holds 80 skills in this directory. The repository was last updated on October 6, 2026.
Source: Mathews-Tom/armory on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.