指南

SDK 中的代理技能

使用 Claude 代理 SDK 中的代理技能擴展 Claude 的專業功能

概述

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

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

技能如何與 SDK 配合使用

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

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

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

默認行為：默認情況下，SDK 不加載任何文件系統設置。要使用技能，您必須在選項中明確配置 settingSources: ['user', 'project']（TypeScript）或 setting_sources=["user", "project"]（Python）。

在 SDK 中使用技能

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

在 allowed_tools 配置中包含 "Skill"
配置 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())

技能位置

根據您的 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 中的代理技能：包含示例的完整指南
代理技能最佳實踐：編寫指南和命名約定

工具限制

SKILL.md 中的 allowed-tools 前置事項字段僅在直接使用 Claude Code CLI 時受支持。通過 SDK 使用技能時不適用。

使用 SDK 時，通過查詢配置中的主 allowedTools 選項控制工具訪問。

要在 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 技能故障排除部分。

SDK 中的代理技能

使用 Claude 代理 SDK 中的代理技能擴展 Claude 的專業功能

概述

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

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

技能如何與 SDK 配合使用

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

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

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

在 SDK 中使用技能

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

在 allowed_tools 配置中包含 "Skill"
配置 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())

技能位置

根據您的 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 中的代理技能：包含示例的完整指南
代理技能最佳實踐：編寫指南和命名約定

工具限制

SKILL.md 中的 allowed-tools 前置事項字段僅在直接使用 Claude Code CLI 時受支持。通過 SDK 使用技能時不適用。

使用 SDK 時，通過查詢配置中的主 allowedTools 選項控制工具訪問。

要在 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 技能故障排除部分。

SDK 中的代理技能

概述

技能如何與 SDK 配合使用

在 SDK 中使用技能

技能位置

創建技能

工具限制

發現可用技能

測試技能

故障排除

找不到技能

技能未被使用

其他故障排除

相關文檔

技能指南

SDK 資源

SDK 中的代理技能

概述

技能如何與 SDK 配合使用

在 SDK 中使用技能

技能位置

創建技能

工具限制

發現可用技能

測試技能

故障排除

找不到技能

技能未被使用

其他故障排除

相關文檔

技能指南

SDK 資源