SDK 中的代理技能

概述

代理技能使用專業功能擴展 Claude，Claude 會在相關時自動調用這些技能。技能被打包為 SKILL.md 文件，包含說明、描述和可選的支持資源。

有關技能的全面信息，包括優勢、架構和編寫指南，請參閱代理技能概述。

技能如何與 SDK 配合使用

使用 Claude 代理 SDK 時，技能具有以下特點：

1. 定義為文件系統工件：在特定目錄（.claude/skills/）中創建為 SKILL.md 文件
2. 從文件系統加載：技能從配置的文件系統位置加載。您必須指定 settingSources（TypeScript）或 setting_sources（Python）以從文件系統加載技能
3. 自動發現：加載文件系統設置後，技能元數據在啟動時從用戶和項目目錄中發現；觸發時加載完整內容
4. 由模型調用：Claude 根據上下文自主選擇何時使用它們
5. 通過 allowed_tools 啟用：將 "Skill" 添加到您的 allowed_tools 以啟用技能

與子代理（可以以編程方式定義）不同，技能必須創建為文件系統工件。SDK 不提供用於註冊技能的編程 API。

在 SDK 中使用技能

要在 SDK 中使用技能，您需要：

1. 在 allowed_tools 配置中包含 "Skill"
2. 配置 settingSources/setting_sources 以從文件系統加載技能

配置完成後，Claude 會自動從指定目錄發現技能，並在與用戶請求相關時調用它們。

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
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool
    )

    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
    allowedTools: ["Skill", "Read", "Write", "Bash"]  // Enable Skill tool
  }
})) {
  console.log(message);
}

技能位置

根據您的 settingSources/setting_sources 配置，技能從文件系統目錄加載：

• 項目技能（.claude/skills/）：通過 git 與您的團隊共享 - 當 setting_sources 包含 "project" 時加載
• 用戶技能（~/.claude/skills/）：跨所有項目的個人技能 - 當 setting_sources 包含 "user" 時加載
• 插件技能：與已安裝的 Claude Code 插件捆綁

創建技能

技能定義為包含具有 YAML 前置事項和 Markdown 內容的 SKILL.md 文件的目錄。description 字段確定 Claude 何時調用您的技能。

示例目錄結構：

.claude/skills/processing-pdfs/
└── SKILL.md

有關創建技能的完整指導，包括 SKILL.md 結構、多文件技能和示例，請參閱：

• Claude Code 中的代理技能：包含示例的完整指南
• 代理技能最佳實踐：編寫指南和命名約定

工具限制

要在 SDK 應用程序中限制技能的工具，請使用 allowedTools 選項：

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # Restricted toolset
)

async for message in query(
    prompt="Analyze the codebase structure",
    options=options
):
    print(message)

發現可用技能

要查看 SDK 應用程序中可用的技能，只需詢問 Claude：

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill"]
)

async for message in query(
    prompt="What Skills are available?",
    options=options
):
    print(message)

Claude 將根據您當前的工作目錄和已安裝的插件列出可用的技能。

測試技能

通過提出與技能描述相匹配的問題來測試技能：

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Bash"]
)

async for message in query(
    prompt="Extract text from invoice.pdf",
    options=options
):
    print(message)

如果描述與您的請求相匹配，Claude 會自動調用相關技能。

故障排除

找不到技能

檢查 settingSources 配置：只有在明確配置 settingSources/setting_sources 時才會加載技能。這是最常見的問題：

# Wrong - Skills won't be loaded
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Correct - Skills will be loaded
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

有關 settingSources/setting_sources 的更多詳細信息，請參閱 TypeScript SDK 參考或 Python SDK 參考。

檢查工作目錄：SDK 相對於 cwd 選項加載技能。確保它指向包含 .claude/skills/ 的目錄：

# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # Must contain .claude/skills/
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

有關完整模式，請參閱上面的「在 SDK 中使用技能」部分。

驗證文件系統位置：

# Check project Skills
ls .claude/skills/*/SKILL.md

# Check personal Skills
ls ~/.claude/skills/*/SKILL.md

技能未被使用

檢查技能工具是否已啟用：確認 "Skill" 在您的 allowedTools 中。

檢查描述：確保它具體且包含相關關鍵字。有關編寫有效描述的指導，請參閱代理技能最佳實踐。

其他故障排除

有關一般技能故障排除（YAML 語法、調試等），請參閱 Claude Code 技能故障排除部分。

相關文檔

技能指南

• Claude Code 中的代理技能：包含創建、示例和故障排除的完整技能指南
• 代理技能概述：概念概述、優勢和架構
• 代理技能最佳實踐：有效技能的編寫指南
• 代理技能食譜：示例技能和模板

SDK 資源

• SDK 中的子代理：類似的基於文件系統的代理，具有編程選項
• SDK 中的斜杠命令：用戶調用的命令
• SDK 概述：一般 SDK 概念
• TypeScript SDK 參考：完整 API 文檔
• Python SDK 參考：完整 API 文檔