SDK 中的 Agent Skills

概述

Agent Skills 為 Claude 擴展了專業能力，Claude 會在相關時自主調用這些能力。Skills 以 SKILL.md 檔案的形式打包，包含指令、描述和可選的支援資源。

有關 Skills 的完整資訊，包括優勢、架構和編寫指南，請參閱 Agent Skills 概述。

Skills 如何與 SDK 配合運作

使用 Claude Agent SDK 時，Skills：

1. 定義為檔案系統產物：以 SKILL.md 檔案的形式建立在特定目錄中（.claude/skills/）
2. 從檔案系統載入：Skills 從配置的檔案系統位置載入。您必須指定 settingSources（TypeScript）或 setting_sources（Python）才能從檔案系統載入 Skills
3. 自動發現：一旦載入檔案系統設定，Skill 中繼資料會在啟動時從使用者和專案目錄中被發現；完整內容在觸發時載入
4. 模型調用：Claude 根據上下文自主選擇何時使用它們
5. 透過 allowed_tools 啟用：將 "Skill" 加入您的 allowed_tools 以啟用 Skills

與子代理（可以透過程式化方式定義）不同，Skills 必須建立為檔案系統產物。SDK 不提供用於註冊 Skills 的程式化 API。

在 SDK 中使用 Skills

要在 SDK 中使用 Skills，您需要：

1. 在您的 allowed_tools 配置中包含 "Skill"
2. 配置 settingSources/setting_sources 以從檔案系統載入 Skills

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        cwd="/path/to/project",  # 包含 .claude/skills/ 的專案
        setting_sources=["user", "project"],  # 從檔案系統載入 Skills
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # 啟用 Skill 工具
    )

    async for message in query(
        prompt="Help me process this PDF document",
        options=options
    ):
        print(message)

asyncio.run(main())

Skill 位置

Skills 根據您的 settingSources/setting_sources 配置從檔案系統目錄載入：

• 專案 Skills（.claude/skills/）：透過 git 與團隊共享 - 當 setting_sources 包含 "project" 時載入
• 使用者 Skills（~/.claude/skills/）：跨所有專案的個人 Skills - 當 setting_sources 包含 "user" 時載入
• 外掛 Skills：與已安裝的 Claude Code 外掛捆綁在一起

建立 Skills

Skills 定義為包含 SKILL.md 檔案的目錄，該檔案具有 YAML 前置資料和 Markdown 內容。description 欄位決定 Claude 何時調用您的 Skill。

範例目錄結構：

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

有關建立 Skills 的完整指南，包括 SKILL.md 結構、多檔案 Skills 和範例，請參閱：

• Claude Code 中的 Agent Skills：包含範例的完整指南
• Agent Skills 最佳實踐：編寫指南和命名慣例

工具限制

要在 SDK 應用程式中限制 Skills 的工具，請使用 allowedTools 選項：

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # 從檔案系統載入 Skills
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # 受限工具集
)

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

發現可用的 Skills

要查看 SDK 應用程式中有哪些可用的 Skills，只需詢問 Claude：

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # 從檔案系統載入 Skills
    allowed_tools=["Skill"]
)

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

Claude 將根據您目前的工作目錄和已安裝的外掛列出可用的 Skills。

測試 Skills

透過提出與 Skills 描述相符的問題來測試它們：

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # 從檔案系統載入 Skills
    allowed_tools=["Skill", "Read", "Bash"]
)

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

如果描述與您的請求相符，Claude 會自動調用相關的 Skill。

疑難排解

找不到 Skills

檢查 settingSources 配置：Skills 僅在您明確配置 settingSources/setting_sources 時才會載入。這是最常見的問題：

# 錯誤 - Skills 不會被載入
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# 正確 - Skills 將被載入
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # 載入 Skills 所必需
    allowed_tools=["Skill"]
)

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

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

# 確保您的 cwd 指向包含 .claude/skills/ 的目錄
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # 必須包含 .claude/skills/
    setting_sources=["user", "project"],  # 載入 Skills 所必需
    allowed_tools=["Skill"]
)

請參閱上方的「在 SDK 中使用 Skills」章節以了解完整模式。

驗證檔案系統位置：

# 檢查專案 Skills
ls .claude/skills/*/SKILL.md

# 檢查個人 Skills
ls ~/.claude/skills/*/SKILL.md

Skill 未被使用

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

檢查描述：確保描述具體且包含相關關鍵字。請參閱 Agent Skills 最佳實踐 以獲取撰寫有效描述的指南。

其他疑難排解

有關一般 Skills 疑難排解（YAML 語法、除錯等），請參閱 Claude Code Skills 疑難排解章節。

相關文件

Skills 指南

• Claude Code 中的 Agent Skills：包含建立、範例和疑難排解的完整 Skills 指南
• Agent Skills 概述：概念概述、優勢和架構
• Agent Skills 最佳實踐：有效 Skills 的編寫指南
• Agent Skills 食譜：範例 Skills 和範本

SDK 資源

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