用途
agent-sdk-builder 是一项用于指导开发者使用 Claude Agent SDK 编写程序的技能。它的核心区分点在于：Agent SDK（claude-agent-sdk）运行的是带内置工具的完整智能体循环，而 anthropic 客户端 SDK 只做原始 API 调用。当你需要的是一个能自主使用工具的智能体、而不是一次聊天补全时，应使用 Agent SDK。该技能适用于希望通过程序化方式构建能够读取文件、编写代码、运行命令、搜索网络并委派子智能体的应用场景。
主要能力
技能覆盖两个语言版本：
- TypeScript：包名 @anthropic-ai/claude-agent-sdk，安装命令
npm install @anthropic-ai/claude-agent-sdk，入口为 query()，源码位于 anthropics/claude-agent-sdk-typescript。 - Python：包名 claude-agent-sdk，安装命令
pip install claude-agent-sdk，入口为 query()，源码位于 anthropics/claude-agent-sdk-python。
两者均通过 ANTHROPIC_API_KEY 环境变量进行认证。技能说明 CLI 包 @anthropic-ai/claude-code 已随 SDK 一同提供，无需单独安装。
技能还提供了按需求选择实现形态的对照表，包括：单次任务用 query()；需要保留上下文的多轮对话用 ClaudeSDKClient（Python）或带 resume 的 query()；通过 resume 加 forkSession 在不改变原会话的情况下分支对话；用 agents 配合 Agent 工具委派专门工作；通过进程内 MCP 服务器为智能体提供自定义函数；通过 plugins 和 settingSources 复用已有 Claude Code 插件；用 outputFormat 配合 JSON schema 获得机器可读结果；用 allowedTools / disallowedTools / permissionMode 做粗粒度权限控制；用 PreToolUse 钩子保证每次调用都满足的规则；用 canUseTool 在代码中处理未决请求；用沙箱与容器隔离运行不可信工作；以及部署到临时或长期运行的主机。
使用方式
技能建议按以下步骤进行：
-
检测环境：通过 package.json 是否声明 @anthropic-ai/claude-agent-sdk 判断 TypeScript，通过 pyproject.toml、requirements.txt 或 uv.lock 中是否声明 claude-agent-sdk 判断 Python；用
npm ls @anthropic-ai/claude-agent-sdk或pip show claude-agent-sdk记录已安装版本；若未安装则说明并安装当前发行版；若版本被固定且低于当前版本，应遵从固定版本。 -
选择形态：根据上述需求对照表挑选用法，并只加载该行对应的参考文件，避免一次加载全部五个参考文件。
-
安全模型：区分三种机制——allowedTools / disallowedTools / permissionMode 负责粗粒度策略；PreToolUse 钩子负责始终生效的强制执行，在权限解析之前对每次匹配调用运行；canUseTool 只作为交互式兜底，仅处理此前未被规则、模式或钩子解决的调用。技能提醒：被加入允许列表的调用不会到达 canUseTool，因此把校验放在那里会在工具获批后悄然失效；disallowedTools 是唯一的硬性阻断，优先级高于 bypassPermissions。此外建议为任何自主任务设置 maxTurns 和 maxBudgetUsd，将密钥排除在提示词之外（改用环境变量或 MCP 工具），并在容器中隔离不可信工作。
-
构建与验证：编写满足任务的最小程序，避免添加未经验证的选项；对每个 API 敏感细节先按第一层（项目已安装的 SDK 类型定义）解析，再按第二层（官方文档）解析；在项目支持下进行类型检查（如
tsc --noEmit）；先用低成本提示并设置较低的 maxTurns 与 maxBudgetUsd 试运行一次；报告哪些事实来自已安装 SDK、哪些来自文档，并指明无法核实的内容。
技能强调文档时效性：SDK 变化很快，选项结构、工具名称、默认值乃至整个功能都可能在版本间变动（例如 fork_session 改变了类型，plugins 从路径改为配置对象，TypeScript V2 预览被完全移除）。因此应将技能中的知识视为入门指引而非权威依据。权威性分为三层：项目已安装的 SDK 类型定义优先级最高；其次是官方文档 https://code.claude.com/docs/en/agent-sdk/；技能自带参考最低。
适用场景
适合需要在自有程序中嵌入自主编码智能体或工具调用智能体的开发者，覆盖 TypeScript 与 Python 项目，涉及会话管理、子智能体委派、自定义工具、插件复用、结构化输出、权限与安全、部署托管等环节。
限制
技能明确指出其知识可能滞后于 SDK 实际版本，不应当作签名、选项结构、默认值或功能是否存在的最终依据。参考文件中标记 (verify) 的条目表示在最近刷新时未能通过第二层核实，属于未确认而非确认不存在。推理模式相关内容属于 prompt-engineer 智能体，不在本 SDK 技能范围内。具体定价、收费、平台效果等信息资料中未提供。