SDK 中的 Agent Skills
使用 Claude Agent SDK 中的 Agent Skills 扩展 Claude 的专业能力
概述
Agent Skills 通过专业能力扩展 Claude，Claude 会在相关时自动调用这些能力。Skills 被打包为 SKILL.md 文件，包含说明、描述和可选的支持资源。
有关 Skills 的全面信息，包括优势、架构和编写指南，请参阅 Agent Skills 概述。
Skills 如何与 SDK 配合使用
使用 Claude Agent SDK 时，Skills 的工作方式如下：
- 定义为文件系统工件：在特定目录（
.claude/skills/）中创建为SKILL.md文件 - 从文件系统加载：Skills 从由
settingSources（TypeScript）或setting_sources（Python）管理的文件系统位置加载 - 自动发现：加载文件系统设置后，在启动时从用户和项目目录发现 Skill 元数据；触发时加载完整内容
- 由模型调用：Claude 根据上下文自动选择何时使用它们
- 通过
skills选项过滤：发现的 Skills 默认启用。传递 Skill 名称列表、"all"或[]来控制会话中可用的 Skills
与子代理（可以通过编程方式定义）不同，Skills 必须创建为文件系统工件。SDK 不提供用于注册 Skills 的编程 API。
在 SDK 中使用 Skills
在 query() 上设置 skills 选项以控制会话中可用的 Skills。省略时，发现的 Skills 启用且 Skill 工具可用，与 CLI 行为匹配。传递 "all" 以启用每个发现的 Skill，传递 Skill 名称列表以仅启用那些，或传递 [] 以禁用所有。设置 skills 时，SDK 自动将 Skill 工具添加到 allowedTools。如果您还传递显式 tools 列表，请在该列表中包含 "Skill"，以便 Claude 可以调用 skills。
配置后，Claude 自动从文件系统发现 Skills 并在与用户请求相关时调用它们。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
cwd="/path/to/project", # Project with .claude/skills/
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all", # Enable every discovered Skill
allowed_tools=["Read", "Write", "Bash"],
)
async for message in query(
prompt="Help me process this PDF document", options=options
):
print(message)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: "/path/to/project", // Project with .claude/skills/
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all", // Enable every discovered Skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
要仅启用特定 Skills，请传递它们的名称。名称与 SKILL.md 中的 name 字段或 Skill 的目录名称匹配。对于插件提供的 Skills，使用 plugin:skill。
options = ClaudeAgentOptions(skills=["pdf", "docx"])
const options = { skills: ["pdf", "docx"] };
skills 选项是上下文过滤器，不是沙箱。未列出的 Skills 对模型隐藏，并被 Skill 工具拒绝，但它们的文件仍在磁盘上，可通过 Read 和 Bash 访问。
Skill 位置
Skills 根据您的 settingSources/setting_sources 配置从文件系统目录加载：
- 项目 Skills（
.claude/skills/）：通过 git 与您的团队共享 - 当setting_sources包含"project"时加载 - 用户 Skills（
~/.claude/skills/）：跨所有项目的个人 Skills - 当setting_sources包含"user"时加载 - 插件 Skills：与已安装的 Claude Code 插件捆绑
创建 Skills
Skills 定义为包含带有 YAML frontmatter 和 Markdown 内容的 SKILL.md 文件的目录。description 字段确定 Claude 何时调用您的 Skill。
示例目录结构：
.claude/skills/processing-pdfs/
└── SKILL.md
有关创建 Skills 的完整指导，包括 SKILL.md 结构、多文件 Skills 和示例，请参阅：
- Claude Code 中的 Agent Skills：包含示例的完整指南
- Agent Skills 最佳实践：编写指南和命名约定
工具限制
要在 SDK 应用程序中控制 Skills 的工具访问，使用 allowedTools 预先批准特定工具。没有 canUseTool 回调时，列表中没有的任何内容都被拒绝：
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)
async for message in query(prompt="Analyze the codebase structure", options=options):
print(message)
for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk" // Deny anything not in allowedTools
}
})) {
console.log(message);
}
发现可用的 Skills
要查看 SDK 应用程序中可用的 Skills，只需询问 Claude：
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
)
async for message in query(prompt="What Skills are available?", options=options):
print(message)
for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all"
}
})) {
console.log(message);
}
Claude 将根据您当前的工作目录和已安装的插件列出可用的 Skills。
测试 Skills
通过提出与其描述匹配的问题来测试 Skills：
options = ClaudeAgentOptions(
cwd="/path/to/project",
setting_sources=["user", "project"], # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Bash"],
)
async for message in query(prompt="Extract text from invoice.pdf", options=options):
print(message)
for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Bash"]
}
})) {
console.log(message);
}
如果描述与您的请求匹配，Claude 会自动调用相关的 Skill。
故障排除
找不到 Skills
检查 settingSources 配置：Skills 通过 user 和 project 设置源发现。如果显式设置 settingSources/setting_sources 并省略这些源，Skills 不会加载：
# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")
# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
)
// Skills not loaded: settingSources excludes user and project
const options = {
settingSources: [],
skills: "all"
};
// Skills loaded: user and project sources included
const options = {
settingSources: ["user", "project"],
skills: "all"
};
有关 settingSources/setting_sources 的更多详情，请参阅 TypeScript SDK 参考 或 Python SDK 参考。
检查工作目录：SDK 从 cwd 选项中的 .claude/skills/ 以及直到仓库根目录的每个父目录加载 Skills。确保 cwd 指向包含 .claude/skills/ 的目录或其下方目录，且在同一仓库内：
# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project", # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"], # Loads skills from these sources
skills="all",
)
// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};
有关完整模式，请参阅上面的"在 SDK 中使用 Skills"部分。
验证文件系统位置：
# Check project Skills
ls .claude/skills/*/SKILL.md
# Check personal Skills
ls ~/.claude/skills/*/SKILL.md
Skill 未被使用
检查 skills 选项：如果传递了 skills 列表，确认 Skill 的名称已包含。传递 [] 会禁用所有 Skills。
检查描述：确保它具体且包含相关关键字。有关编写有效描述的指导，请参阅 Agent Skills 最佳实践。
其他故障排除
有关一般 Skills 故障排除（YAML 语法、调试等），请参阅 Claude Code Skills 故障排除部分。
相关文档
Skills 指南
- Claude Code 中的 Agent Skills：包含创建、示例和故障排除的完整 Skills 指南
- Agent Skills 概述：概念概述、优势和架构
- Agent Skills 最佳实践：有效 Skills 的编写指南
- Agent Skills 食谱：示例 Skills 和模板
SDK 资源
- SDK 中的子代理：具有编程选项的类似文件系统代理
- SDK 中的 Slash Commands：用户调用的命令
- SDK 概述：常规 SDK 概念
- TypeScript SDK 参考：完整 API 文档
- Python SDK 参考：完整 API 文档