字节笔记本
2026年2月17日 · 约 10 分钟读完
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 中
- 检查描述：确保描述具体并包含相关关键词