字节笔记本
2026年2月17日
Claude Agent SDK 中的 Agent Skills 使用指南
本文详细介绍如何在 Claude Agent SDK 中使用 Agent Skills，包括 Skills 的工作原理、配置方法、创建指南以及故障排查。
概述
Agent Skills 通过专门的 SKILL.md 文件扩展 Claude 的能力。当用户请求与 Skill 描述匹配时，Claude 会自动调用相应的 Skill。
参考文档: Claude Agent SDK 官方文档
Skills 在 SDK 中的工作原理
使用 Claude Agent SDK 时，Skills 的工作方式如下：
- 文件系统产物：以 SKILL.md 文件形式存在于特定目录（.claude/skills/）
- 从文件系统加载：必须通过 settingSources（TypeScript）或 setting_sources（Python）配置来加载 Skills
- 自动发现：文件系统设置加载后，Skill 元数据在启动时被发现；触发时加载完整内容
- 模型调用：Claude 根据上下文自主决定何时使用
- 通过 allowed_tools 启用：添加 "Skill" 到 allowed_tools 以启用 Skills
与可以通过编程定义的子代理不同，Skills 必须作为文件系统产物创建。SDK 不提供用于注册 Skills 的编程 API。
在 SDK 中使用 Skills
要在 SDK 中使用 Skills，需要：
- 在 allowed_tools 配置中包含 "Skill"
- 配置 settingSources/setting_sources 从文件系统加载 Skills
配置完成后，Claude 会自动从指定目录发现 Skills，并在相关用户请求时调用它们。
Python 示例
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
cwd="/path/to/project",
setting_sources=["user", "project"],
allowed_tools=["Skill", "Read", "Write", "Bash"],
)
async for message in query(
prompt="Help me process this PDF document", options=options
):
print(message)
asyncio.run(main())TypeScript 示例
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",
settingSources: ["user", "project"],
allowedTools: ["Skill", "Read", "Write", "Bash"]
}
})) {
console.log(message);
}Skill 位置
Skills 根据 settingSources/setting_sources 配置从文件系统目录加载：
- 项目 Skills（.claude/skills/）：通过 git 与团队共享
- 用户 Skills（~/.claude/skills/）：跨所有项目的个人 Skills
- 插件 Skills：随安装的 Claude Code 插件捆绑
创建 Skills
Skills 定义为包含 SKILL.md 文件的目录，该文件包含 YAML 前置数据和 Markdown 内容。description 字段决定 Claude 何时调用你的 Skill。
示例目录结构：
.claude/skills/processing-pdfs/
└── SKILL.md工具限制
allowed-tools 前置数据字段仅在直接使用 Claude Code CLI 时支持。在 SDK 中使用 Skills 时不适用。
要在 SDK 应用中限制 Skills 的工具访问，使用主 allowedTools 选项。
Python
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
allowed_tools=["Skill", "Read", "Grep", "Glob"],
)TypeScript
for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"],
allowedTools: ["Skill", "Read", "Grep", "Glob"]
}
})) {
console.log(message);
}发现可用 Skills
要查看 SDK 应用中可用的 Skills，只需询问 Claude：
Python
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
allowed_tools=["Skill"],
)
async for message in query(prompt="What Skills are available?", options=options):
print(message)TypeScript
for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"],
allowedTools: ["Skill"]
}
})) {
console.log(message);
}测试 Skills
通过询问与描述匹配的问题来测试 Skills：
Python
options = ClaudeAgentOptions(
cwd="/path/to/project",
setting_sources=["user", "project"],
allowed_tools=["Skill", "Read", "Bash"],
)
async for message in query(prompt="Extract text from invoice.pdf", options=options):
print(message)TypeScript
for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"],
allowedTools: ["Skill", "Read", "Bash"]
}
})) {
console.log(message);
}故障排查
Skills 未找到
检查 settingSources 配置：只有显式配置 settingSources/setting_sources 时才会加载 Skills。
# 错误 - Skills 不会被加载
options = ClaudeAgentOptions(allowed_tools=["Skill"])
# 正确 - Skills 会被加载
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
allowed_tools=["Skill"],
)检查工作目录：SDK 相对于 cwd 选项加载 Skills。确保它指向包含 .claude/skills/ 的目录。
验证文件系统位置：
ls .claude/skills/*/SKILL.md
ls ~/.claude/skills/*/SKILL.mdSkill 未被使用
- 检查 Skill 工具是否启用：确认 "Skill" 在你的 allowedTools 中
- 检查描述：确保描述具体并包含相关关键词