跳轉到主要內容

​
概述

Agent Skills 使用專門功能擴展 Claude，Claude 會在相關時自動調用這些功能。Skills 被打包為 SKILL.md 文件，包含說明、描述和可選的支持資源。 有關 Skills 的全面信息，包括優勢、架構和編寫指南，請參閱 Agent Skills 概述。

​
Skills 如何與 SDK 配合使用

使用 Claude Agent SDK 時，Skills 的特點是：
  1. 定義為文件系統工件：在特定目錄（.claude/skills/）中創建為 SKILL.md 文件
  2. 從文件系統加載：Skills 從由 settingSources（TypeScript）或 setting_sources（Python）控制的文件系統位置加載
  3. 自動發現：加載文件系統設置後，在啟動時從用戶和項目目錄發現 Skill 元數據；觸發時加載完整內容
  4. 由模型調用：Claude 根據上下文自動選擇何時使用它們
  5. 通過 skills 選項進行篩選：發現的 Skills 默認啟用。傳遞 Skill 名稱列表、"all" 或 [] 來控制會話中可用的 Skills
與子代理不同（可以以編程方式定義），Skills 必須創建為文件系統工件。SDK 不提供用於註冊 Skills 的編程 API。
Skills 通過文件系統設置源發現。使用默認 query() 選項時，SDK 加載用戶和項目源，因此 ~/.claude/skills/、<cwd>/.claude/skills/ 和 <cwd> 的任何父目錄（直到存儲庫根目錄）中的 .claude/skills/ 中的 Skills 可用。如果您明確設置 settingSources，請包含 'user' 或 'project' 以保持 Skill 發現，或使用 plugins 選項 從特定路徑加載 Skills。

​
在 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())
要僅啟用特定 Skills，請傳遞它們的名稱。名稱與 SKILL.md 中的 name 欄位或 Skill 的目錄名稱匹配。對於外掛提供的 Skills，使用 plugin:skill。 
options = ClaudeAgentOptions(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 和示例，請參閱：

​
工具限制

SKILL.md 中的 allowed-tools frontmatter 字段僅在直接使用 Claude Code CLI 時受支持。通過 SDK 使用 Skills 時不適用。使用 SDK 時，通過查詢配置中的主 allowedTools 選項控制工具訪問。
要在 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)

​
發現可用的 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)
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)
如果描述與您的請求相匹配，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",
)
有關 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",
)
有關完整模式，請參閱上面的「在 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 指南

​
SDK 資源