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 最佳實踐：編寫指南和命名約定
- Agent Skills Cookbook：示例 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 Cookbook：示例 Skills 和模板
SDK 資源
- SDK 中的子代理：類似的基於文件系統的代理，具有編程選項
- SDK 中的斜杠命令：用戶調用的命令
- SDK 概述：一般 SDK 概念
- TypeScript SDK 參考：完整 API 文檔
- Python SDK 參考：完整 API 文檔