claude-agent-sdk-agent-creation（ClaudeAgentSDK代理创建）Skill 是什么？如何安装使用？

ClaudeAgentSDK代理创建Skill：用 TypeScript 十分钟搭好一个可用的 Claude AI 代理

• 它是做什么的：这是一份围绕 Claude Agent SDK（TypeScript 版）的「代理创建与配置」实操指南型技能，把代理初始化、系统提示、工具权限、目录结构、认证方式、最佳实践与常见反模式整理成了可直接参考的代码模板。
• 它解决什么问题：很多开发者在第一次用 SDK 创建代理时，会卡在「模型怎么指定」「系统提示从哪里加载」「工具权限怎么收窄」「API Key 怎么安全注入」这些细节上，反复试错。这个技能把这些高频问题一次性讲清。
• 它的形态比较特殊：技能自身标注为非用户主动调用（user-invocable: false），也就是说它不是让你输入一条命令去执行，而是在你创建或配置 Claude 代理时作为上下文知识被参考，属于「写得越久越省事」的参考型技能。
• 核心产出：一套可直接复制使用的 TypeScript 配置写法，覆盖 Anthropic 官方 API、Amazon Bedrock、Google Vertex AI、Azure 等认证路径。
• 适合谁用：正在用或准备用 Claude Agent SDK 搭建 AI 代理的后端工程师、AI 应用开发者、以及想把内部工具接进代理工作流的技术团队。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能中文名：ClaudeAgentSDK代理创建Skill 技能英文名：claude-agent-sdk-agent-creation 技能ID：14023

它要解决的问题非常具体：Claude Agent SDK 提供了丰富的配置项——模型、系统提示、设置源、工具白名单与黑名单、权限模式、多云认证——但选项一多，新手很容易写出「能跑但埋坑」的代码，比如硬编码 API Key、不指定模型依赖默认值、同时把某个工具放进允许列表又放进禁止列表造成权限冲突。这个技能把这些坑提前标了出来，并给出推荐写法。

「一键安装」提升开发效率的思路

AI 技能的安装逻辑与插件类似：把技能文件放入技能目录后，AI 助手在遇到相关任务时会自动参考其中的内容，而不需要你每次手动粘贴一长串文档。

安装前提：

1. 你使用的 AI 编程环境支持 AI 技能（Skill）机制，且已开启技能加载；
2. 本地具备 Node.js 与 TypeScript 开发环境（因为技能内容以 TypeScript 示例为主）；
3. 如果你要真正运行代理代码，还需要准备对应模型的访问凭证，例如 Anthropic API Key，或 Amazon Bedrock、Google Vertex AI、Azure 的云凭证。

安装步骤（通用流程）：

1. 从技能市场或技能仓库中找到该技能（英文名 claude-agent-sdk-agent-creation），执行安装或下载；
2. 确认技能文件已被放入当前项目或用户级的技能目录中，目录结构通常形如 .claude/skills/<技能名>/SKILL.md，具体路径以官方说明为准；
3. 重新加载或重启你的 AI 编程助手，使其重新扫描技能目录；
4. 在对话中提出与「创建 Claude 代理」「配置 SDK 工具权限」相关的需求，观察助手是否会引用该技能的内容。

验证是否生效：可以让助手「用 Claude Agent SDK 写一个最小可运行的代理初始化代码」。如果它输出了带 model、systemPrompt 或 settingSources、allowedTools 的完整配置，并提醒你不要硬编码 API Key，说明技能已被正确加载。若没有反应，优先检查技能目录位置、文件命名与权限，具体命令与入口请以官方说明为准。

需要说明的是，该技能标注为非用户主动调用（user-invocable: false），所以它通常不会以「/技能名」这样的命令形式被手动触发，而是作为背景知识参与到代理创建类任务中。

该技能的主要功能和特点

• 代理初始化模板：给出 new Agent({...}) 的标准写法，包含模型选择、系统提示、设置源、允许工具四个关键字段，避免从零拼配置。
• 系统提示的三种来源讲得清楚：直接在 systemPrompt 里写、通过 settingSources: ['project'] 加载项目级 .claude/CLAUDE.md、通过 settingSources: ['user'] 加载用户级 ~/.claude/CLAUDE.md，让「项目规范」与「个人偏好」彻底分离。
• 工具权限的双向控制：既支持 allowedTools 白名单（只放开读文件、写文件、列目录、grep、bash 等），也支持 disallowedTools 黑名单（例如屏蔽 bash 与联网搜索），还提供 permissionMode: 'strict' 这类需要显式批准的严格模式。
• 标准化的目录结构约定：给出 .claude/ 下放 CLAUDE.md、agents/、skills/，源码放 src/index.ts 的推荐布局，团队协作时不会各写各的。
• 多云认证覆盖：Anthropic 官方 API 用 ANTHROPIC_API_KEY；AWS 用 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION 并通过 provider: 'bedrock' 指定；Google Vertex AI 用 GOOGLE_APPLICATION_CREDENTIALS；Azure 用 AZURE_OPENAI_API_KEY 与 AZURE_OPENAI_ENDPOINT。
• 最佳实践与反模式对照：用「好/坏」并列的写法直接展示推荐姿势，例如「始终指定模型」「使用显式设置源」「不要硬编码 API 密钥」「不要混合冲突的权限」。
• 和普通文档的差别：它不是泛泛的概念介绍，而是可复制的配置片段 + 明确的取舍建议，属于「照着写就对」的类型；同时它还与工具集成、上下文管理等相邻技能形成关联，便于继续深入。

如何使用该技能？

第 1 步：准备环境与凭证

确认 Node.js 与 TypeScript 可用，并在环境中导出所需凭证（不要把密钥写进代码）：

export ANTHROPIC_API_KEY="sk-ant-..."

第 2 步：安装并引入 SDK

在项目中安装 Claude Agent SDK（包名以官方说明为准），然后在 TypeScript 文件中引入 Agent：

import { Agent } from '@anthropic-ai/claude-agent-sdk';

第 3 步：创建最小可用代理

const agent = new Agent({
  model: 'claude-3-5-sonnet-20241022',
  systemPrompt: '你是一名擅长 TypeScript 的代码评审助手。',
  settingSources: ['project'],
  allowedTools: ['read_file', 'write_file', 'list_files'],
});

输入说明：model 指定模型版本；systemPrompt 是角色设定；settingSources 决定是否加载项目级 .claude/CLAUDE.md；allowedTools 限定它能调用哪些工具。

输出结果：一个具备明确角色、明确工具边界、并会读取项目规范的代理实例。

第 4 步：按需收紧权限

只读场景可以这样写：

const agent = new Agent({
  model: 'claude-3-5-sonnet-20241022',
  allowedTools: ['read_file', 'list_files', 'grep'],
  permissionMode: 'strict',
});

如果确实要排除高危能力，用 disallowedTools: ['bash', 'web_search']，但不要与 allowedTools 互相矛盾——同一个工具同时出现在两个列表里属于权限冲突，是技能明确指出的反模式。

第 5 步：组织项目目录

project/
├── .claude/
│   ├── CLAUDE.md
│   ├── agents/
│   │   └── specialist.md
│   ├── skills/
│   │   └── my-skill/
│   │       └── SKILL.md
└── src/
    └── index.ts

第 6 步：切换到云厂商（可选）

const agent = new Agent({
  provider: 'bedrock',
  model: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
});

第 7 步：运行与验证

执行你的入口文件，观察代理是否按角色设定回应、是否只调用了被允许的工具。若报认证错误，先检查环境变量是否在当前 shell 生效；若提示模型不存在，检查模型标识与所处区域是否匹配，具体参数以官方说明为准。

同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
claude-agent-sdk-agent-creation（本技能）	面向 Claude Agent SDK 的代理创建配置指南	初始化模板、系统提示来源、工具权限、目录结构、多云认证、最佳实践与反模式	需支持技能的 AI 编程环境；需 TypeScript 基础	首次搭建 Claude 代理、团队统一代理配置规范	优势：配置项讲得细、正反例对照、能规避权限冲突与密钥硬编码；不足：仅覆盖创建与配置阶段，不涉及深度上下文管理与工具生态扩展
直接调用 Anthropic Messages API	最底层的模型调用方式	发送消息、接收回复	门槛低但工作量大，需自行实现工具调用、文件读写等能力	极简的问答型集成	优势：可控性最强；不足：代理循环、工具权限、内存管理都要自己写，效率低
OpenAI Agents SDK 等同类代理框架	通用代理编排框架	代理、工具调用、交接（handoff）、追踪	需理解该框架自身概念体系	多代理协作、跨模型编排	优势：生态成熟、文档丰富；不足：与 Claude 的项目级内存文件、技能体系并非原生对齐，迁移成本存在
LangChain / LangGraph 等编排库	通用 LLM 应用编排	链式编排、状态机、工具集成	学习曲线较陡，抽象层多	复杂多步骤工作流、RAG 应用	优势：组件丰富、可组合性强；不足：轻量代理场景容易过度设计，调试链路较长

选型建议：如果你的技术栈就是 Claude 且需要项目级内存与工具权限的细粒度控制，本技能所对应的 SDK 路径最短；如果要做跨模型、多代理协作的复杂系统，再考虑通用编排框架。

该技能的典型应用场景与实际体验情况

场景一：代码评审代理搭建

角色：后端工程师或技术负责人。痛点：想让 AI 自动读改动文件并给评审意见，但担心它误改代码或执行危险命令。使用方式：用 allowedTools: ['read_file', 'list_files', 'grep'] 只读授权，配合 systemPrompt 设定「资深代码评审员」角色。实际体验：权限收窄后心理负担明显降低，照抄模板即可跑通；注意模型标识要与账号可用模型一致，否则会先卡在模型不存在上。

场景二：团队规范统一

角色：多人协作的研发团队。痛点：每个人都在自己电脑上写系统提示，导致同一个代理在不同人手里行为不一致。使用方式：统一通过 settingSources: ['project'] 加载项目内 .claude/CLAUDE.md，把团队编码规范沉淀进去。实际体验：这是该技能里性价比最高的部分——规范随代码走、随仓库走，改一次全员生效；注意不要把个人偏好写进项目级文件。

场景三：企业多云部署

角色：企业架构师或平台团队。痛点：公司统一走 Amazon Bedrock 或 Vertex AI，不直连官方 API。使用方式：按技能给出的环境变量与 provider: 'bedrock' 配置切换。实际体验：认证段落的清单式写法省去了翻文档的时间；注意不同云区域的模型标识不同，模型 ID 需按实际部署环境核对。

场景四：内部自动化助手

角色：效率工具爱好者或运维同学。痛点：想让代理帮忙整理文件、批量查看日志，但又怕它越权。使用方式：disallowedTools 屏蔽 bash 与 web_search，再配 permissionMode: 'strict'。实际体验：安全边界清晰，适合先小范围试用再逐步放开；注意每次放开权限都要重新评估一次副作用。

整体上手难度：低到中等。有 TypeScript 基础的人基本可以照抄；真正的门槛不在语法，而在「选择哪个设置源、放开哪些工具」这类工程判断。

该技能能为用户带来的价值

• 把试错成本前置消化：反模式章节直接列出「硬编码密钥」「权限冲突」「不指定模型」三类高频错误，每避开一个都意味着少一次线上排查。
• 缩短首次跑通时间：从读官方文档到写出可用配置，通常需要来回查找多个页面；本技能把初始化、系统提示、工具权限、认证合并成一条路径，首次搭建的时间被显著压缩。
• 降低安全风险：默认引导使用环境变量注入密钥、用白名单最小化工具权限、用 strict 模式要求显式批准，这三点是 AI 代理最容易出事的地方。
• 提升团队协作一致性：目录结构与项目级内存的约定，让代理配置变成可评审、可版本管理的代码资产，而不是某个人的本地习惯。
• 长期价值：当代理数量增长、从单个助手变成多个子代理协同时，一套规范的初始化与权限模型会成为后续扩展的地基，避免推倒重来。

常见问题 FAQ

Q1：这个技能怎么安装？装了没反应怎么办？ A：按技能市场或技能仓库的通用流程安装，确认技能文件被放入项目级或用户级技能目录（通常形如 .claude/skills/<技能名>/SKILL.md），然后重新加载 AI 编程助手。由于该技能是非主动调用型（user-invocable: false），它不会以命令形式出现，而是当你提出「创建 Claude 代理」类需求时被引用。没反应时优先检查目录位置、文件命名与加载开关，具体路径与命令以官方说明为准。

Q2：使用这个技能收费吗？ A：技能本身是配置与写法指南，不包含内置的模型调用额度。真正产生费用的是你运行代理时对模型的调用，计费取决于你所用的服务商（Anthropic 官方 API、Amazon Bedrock、Google Vertex AI 或 Azure）的定价策略，具体价格以官方说明为准。

Q3：它适合谁用？不懂 TypeScript 能用吗？ A：主要面向正在用或准备用 Claude Agent SDK 搭建代理的开发者，尤其是第一次接触该 SDK 的人。技能里的示例都是 TypeScript，完全不懂 TypeScript 的话理解成本会比较高；但如果你只是想了解「一个 Claude 代理需要配置哪些东西」，把示例当伪代码读也能获得整体认知。

Q4：它和直接用 LangChain 之类的框架比，该怎么选？ A：如果技术栈是 Claude、需要项目级内存文件与工具权限的细粒度控制、且希望配置尽量轻量，本技能对应的 SDK 路径更直接；如果要跨模型、做多代理协作或复杂状态编排，通用编排框架更合适。二者并不互斥，可以先用 SDK 跑通单代理，再评估是否需要更重的编排层。

Q5：为什么技能里反复强调「不要硬编码 API 密钥」和「不要权限冲突」？ A：硬编码密钥会让凭证随代码进入版本库，存在泄露风险；而同一个工具既在 allowedTools 又在 disallowedTools 中，属于自相矛盾的配置，行为不可预期、排查困难。这两条是技能中最值得记住的硬性约束，也是把原型代码带向生产环境前必须清理的问题。