agent-builder

Agent Builder - Claude SDK 与 CLI 专家

触发词：

• “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”

---

优先使用 Claude Code 无头模式

此技能介绍 Claude Code 的无头模式和 Agent SDK，而非原始 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

为什么这很重要：

• Agent SDK 封装了 Claude Code CLI，不使用原始 Anthropic API
• 身份验证使用现有的 ~/.claude/ 配置，无需 API 密钥
• 所有设置、MCP 服务和配置均继承自你的 Claude Code 设置
• 你可以使用 Claude Code 完整的 Agent 循环、工具和上下文管理功能

规则： 如果代码使用 anthropic.Anthropic()、anthropic.messages.create() 或要求设置 ANTHROPIC_API_KEY，则方案有误。请改用 claude -p 或 claude_agent_sdk。

---

核心功能

1. Claude Agent SDK Python - 使用自定义工具和钩子以编程方式创建 Agent（封装 Claude Code CLI）
2. 无头／打印模式 - 从 CLI、脚本和 CI/CD 运行 Claude Code（claude -p）
3. CLI 参考 - 所有命令、标志和配置选项

全部使用 Claude Code 现有的 ~/.claude/ 身份验证，无需 API 密钥。

---

文档来源

• Agent SDK：https://github.com/anthropics/claude-agent-sdk-python
• 无头模式：https://code.claude.com/docs/en/headless
• CLI 参考：https://code.claude.com/docs/en/cli-reference

---

工作流

1. 了解需求 - 需要哪类 Agent／自动化？
2. 检查依赖项 - 确认 Python 版本、软件包和 Claude Code 安装情况
3. 查阅最新文档 - 细节不明确时，获取相关文档
4. 放心构建 - 编写具备适当错误处理、可用于生产环境的代码
5. 立即测试 - 运行并验证实现

---

参考文件

仅加载与当前任务相关的参考文件。

任务	加载
区分原始 Anthropic API 与 Claude Code SDK 模式	references/api-vs-sdk.md
使用 Agent SDK 编写 Python Agent（安装、查询、客户端、工具、钩子、错误）	references/sdk-python.md
使用无头 claude -p 模式（基础用法、JSON Schema、流式传输、工具审批、会话、系统提示词）	references/headless-cli.md
CLI 命令、标志表、动态子 Agent、权限规则语法	references/cli-reference.md
使用场景模板：CI/CD 流水线、代码审查、自定义分析工具、数据库查询 Agent	references/use-cases.md
Agent SDK 和 CLI／无头模式最佳实践	references/best-practices.md
完整的端到端 Agent 示例（工具 + 钩子 + 客户端）	references/example-agent.md
生成产物的输出格式规范	references/output-format.md

---

安全

• 不要在生产环境中使用 --dangerously-skip-permissions
• 验证自定义工具的输入
• 使用权限规则阻止破坏性命令
• 使用 --max-budget-usd 设置预算上限
• 为敏感操作实现钩子
• 自动化之前，检查允许使用的工具

---

快速决策树

需要……

• 运行一次性查询 → claude -p "query"
• 构建自定义 Agent → 使用 ClaudeSDKClient 的 Agent SDK
• 添加自定义工具 → 使用带 @tool 装饰器的 SDK MCP 服务
• 控制执行过程 → 使用 HookMatcher 的钩子
• 流式传输响应 → --output-format stream-json
• 获取结构化数据 → --json-schema
• 继续对话 → --continue 或 --resume
• 在 CI/CD 中运行 → 将 claude -p 与 --allowedTools 配合使用
• 与应用集成 → 使用 query() 或 ClaudeSDKClient 的 Python SDK

---

何时获取文档

以下情况应获取最新文档：

• API 签名或参数不明确
• 提到了新功能或标志
• 错误消息引用了未知配置
• 实现复杂的钩子或 MCP 服务
• 用户询问特定功能

使用 WebFetch 工具从源 URL 获取最新文档。

---

实现检查清单

编写代码前：

• 验证： 使用 Claude Code 无头模式（claude -p 或 claude_agent_sdk），而非原始 Anthropic API
• 验证： 代码中没有 API 密钥——身份验证来自 ~/.claude/ 配置
• 确认 Python 版本（3.10+）
• 验证 Claude Code CLI 已安装（which claude）
• 使用 uv pip list 检查所需的软件包
• 了解具体用例
• 确定需要使用 SDK 还是 CLI 方案

编写代码后：

• 验证： 代码使用 claude_agent_sdk 或 claude -p，而非 anthropic.Anthropic()
• 验证： 代码中没有 ANTHROPIC_API_KEY 或 api_key= 参数
• 为所有 SDK 异常添加错误处理
• 使用实际安装的 Claude Code 进行测试
• 验证工具权限和安全性
• 设置适当的限制（轮次、预算）
• 记录自定义工具及其用途

---

技能调用

此技能提供：

• 完整的 Agent SDK 实现指南
• 无头模式／CLI 命令构造
• 使用 MCP 服务创建自定义工具
• 用于控制流的钩子实现
• 安全最佳实践
• 按需获取最新文档

询问有关构建 Agent、运行无头命令或使用 CLI 的具体问题。

---

限制

• Agent SDK 仅支持 Python（Python 3.10+）；此处不涵盖 JavaScript 或其他语言绑定。
• 使用任何 SDK 或无头模式前，必须先安装 Claude Code CLI，并通过 ~/.claude/ 完成身份验证。
• 此技能不涵盖原始 Anthropic API 用法（anthropic.Anthropic()）；相关内容请参阅 Anthropic API 文档。
• 通过 SDK 启动的 Agent 进程默认是临时的；如需会话持久化，必须显式使用 --resume 或捕获会话 ID。
• 此技能中的 MCP 服务模式使用 stdio 传输；基于 HTTP 的 MCP 传输需要单独配置，本文不作介绍。