SpyBara
Go Premium

agent-sdk/skills.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 379 additions and 152 deletions.

2026
Thu 10 23:00 Mon 14 22:58 Fri 18 23:58

使用 Skills 擴展 Agent

控制 Claude 在 Claude Agent SDK 會話中可以調用的 Skills，按名稱分派命令，以及編寫會話發現的 Skills

Agent Skills 使用專門功能擴展 Claude，Claude 會在相關時自動調用這些功能。Skills 被打包為 SKILL.md 文件，包含說明、描述和可選的支持資源。本頁面也涵蓋了 Agent SDK 會話中的命令。

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

Skills 如何與 Agent SDK 搭配運作

使用 Claude Agent SDK 時，skills 具有以下特性：

  • 定義為檔案系統成品：你在自己的目錄中建立每個 skill 作為 SKILL.md 檔案，例如 .claude/skills/<name>/SKILL.md
  • 從檔案系統載入：SDK 從由 settingSources（TypeScript）或 setting_sources（Python）控制的檔案系統位置載入 skills
  • 自動探索：一旦檔案系統設定載入，SDK 會在啟動時從使用者和專案目錄探索 skill 中繼資料，並在 Claude 叫用 skill 時載入完整內容
  • 由模型叫用：Claude 根據上下文自主選擇何時使用它們
  • 由使用者叫用：你可以在提示中傳送 /<name> 來直接分派 skill。請參閱 Agent SDK 工作階段中的命令
  • 透過 skills 選項進行範圍設定：探索到的 skills 預設為啟用。傳遞 skill 名稱清單、"all" 或 [] 來控制 Claude 可以叫用哪些 skills

與你可以在 agents 選項中定義的 subagents 不同，你將 skills 建立為磁碟上的檔案。SDK 不提供用於註冊它們的程式設計 API。

在 Agent SDK 中使用 Skills

在 query() 上設置 skills 選項以控制會話中 Claude 可以調用的 Skills。省略時，發現的 Skills 啟用且 Skill 工具可用，與 CLI 行為匹配。傳遞 "all" 以讓 Claude 調用每個發現的 Skill，傳遞 Skill 名稱列表以僅允許那些，或傳遞 [] 以讓 Claude 不調用任何 Skill。

例如，要讓 Claude 僅調用兩個命名的 Skills：

options = ClaudeAgentOptions(skills=["pdf", "docx"])

在會話中設置 Skills

當您設置 skills 時，SDK 會自動將 Skill 工具添加到 allowedTools。如果您也傳遞明確的 tools 列表，請在該列表中包含 "Skill"，以便 Claude 可以調用 Skills。

配置後，Claude 自動從文件系統發現 Skills 並在與使用者請求相關時調用它們。

以下示例在會話中啟用每個發現的 Skill，並預先批准 Skills 通常需要的工具。該示例將 cwd 設置為進程的當前工作目錄，因此請從具有當前目錄或任何父目錄（直到存儲庫根目錄）中的 .claude/skills/ 目錄的項目內運行它：

import asyncio
import os

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
options = ClaudeAgentOptions(
cwd=os.getcwd(),  # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"],  # Load skills from filesystem
skills="all",  # Let Claude invoke 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 已加載

在流的開始附近，SDK 會產生一個子類型為 init 的系統消息。檢查其 skills 陣列以確認您的 Skills 在 Claude 開始工作之前已加載。該陣列包括您已定義的使用者可調用 Skills，以及 Claude Code 包含的捆綁 Skills。

該陣列僅列出使用者可調用的 Skills。具有 frontmatter 中 user-invocable: false 的 Skill 會加載並保持對 Claude 可用，但不會出現在陣列中。該陣列反映會話發現的內容，並列出相同的 Skills，無論它們是否在您的 skills 列表中。

僅允許特定 Skills

要讓 Claude 僅調用特定 Skills，請在 skills 列表中傳遞它們的名稱。名稱與 SKILL.md 中的 name 欄位或 Skill 的目錄名稱匹配。對於外掛提供的 Skills，使用 plugin:skill。

該列表僅接受確切的 Skill 名稱。如果一個條目不能作為確切名稱工作，query() 會在會話開始前拒絕該列表。請參閱 無效的 Skill 名稱錯誤 以了解名稱規則和每個 SDK 引發的錯誤。

模型看不到未列出的 Skills，Skill 工具會拒絕它們，而它們的文件仍保留在磁碟上，並可通過 Read 和 Bash 訪問。限制列表不會限制 按名稱分派。

要讓 Claude 調用每個發現的 Skill，請傳遞 skills: "all" 而不是通配符。

Agent SDK 工作階段中的命令

本節是 SDK 的命令文件。命令是您透過在提示中傳送 /<name> 來執行的任何操作。命令表面上的項目在其支援方式上有所不同：

  • 內建命令：執行編碼到 Claude Code 程序中的邏輯，例如 /compact
  • 捆綁技能：隨 Claude Code 一起提供的提示工件，例如 /code-review
  • 您的技能：您編寫的提示工件，每個都是包含 SKILL.md 檔案的目錄。使用者可呼叫的技能名稱會自動加入表面，因此分派您自己的 /security-check 和執行內建命令的方式相同
  • 自訂命令檔案：一種較舊的工件形式，具有相同的行為，位於 .claude/commands/ 中的平面 Markdown 檔案，其檔案名稱會變成命令名稱。技能是其推薦的後繼者

根據預設，您和 Claude 都可以呼叫任何技能。您可以透過技能的前置資料限制任一路徑。如需這兩個術語的定義，請參閱詞彙表的命令和技能項目。請參閱Claude Code 中的命令以了解每個內建命令，以及使用技能擴展 Claude 以了解兩種工件形式的完整指南。

探索可用命令

您可以透過 SDK 分派無需互動式終端機的命令。system/init 訊息在其 slash_commands 欄位中列出工作階段中可用的命令。需要互動式終端機的命令（例如 /theme 和 /terminal-setup）不會出現在清單中。在工作階段開始時存取該欄位：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Hello Claude",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Available commands:", message.slash_commands);
}
}

列印的清單混合了內建命令、捆綁技能、您的使用者可呼叫技能和 .claude/commands/ 檔案：

Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]

您的使用者可呼叫技能會出現在此清單和確認技能已載入中的 skills 陣列中。slash_commands 清單新增了工作階段中可用的其餘命令。在其前置資料中具有 user-invocable: false 的技能不會出現在任一個中。設定MCP 伺服器的工作階段也可以公開 MCP 提示作為命令。

按名稱分派命令

透過將命令包含在提示字串中來傳送命令，就像傳送一般文字一樣。分派不取決於 skills 選項。傳送 /<name> 會執行使用者可呼叫的技能，即使您的 skills 清單省略了它。作用於對話歷史記錄的命令（例如 /compact）需要先前的訊息才能使用。

使用 `/compact` 壓縮歷史記錄

/compact 命令透過總結較舊的訊息同時保留重要內容來減少對話歷史記錄的大小。壓縮需要現有的對話，其中有足夠的先前訊息要總結。此範例首先有一個對話，然後壓縮它並讀取報告結果的 compact_boundary 系統訊息：

import { query } from "@anthropic-ai/claude-agent-sdk";

// Compaction needs existing history, so have a conversation first
try {
for await (const message of query({
prompt: "Explain what this project does",
options: { maxTurns: 2 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result,
// so the follow-up query below still runs.
console.error(`Session ended with an error: ${error}`);
}

// Compact the same conversation
for await (const message of query({
prompt: "/compact",
options: { continue: true, maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "compact_boundary") {
console.log("Compaction completed");
console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
console.log("Trigger:", message.compact_metadata.trigger);
// Example output:
// Compaction completed
// Pre-compaction tokens: 1842
// Trigger: manual
}
}

使用 `/clear` 重設內容

/clear 命令將對話重設為空內容，因此後續提示以沒有先前對話歷史記錄開始。先前的對話保留在磁碟上。您可以透過將其工作階段 ID 傳遞給resume 選項來返回該對話。

/clear 在串流輸入模式中很有用，您可以在單一連線上傳送多個提示。對於單一查詢 query() 呼叫，每個呼叫已經以空內容開始，因此傳送 /clear 沒有實際效果。改為啟動新的 query()。

創建 Skills

將每個 Skill 創建為包含具有 YAML frontmatter 和 Markdown 內容的 SKILL.md 文件的目錄。description 欄位確定 Claude 何時調用您的 Skill。

示例目錄結構：

.claude/skills/security-check/
└── SKILL.md

選擇發現級別

在兩個最常見的 發現級別 中保存 Skills：

  • 項目 Skills：.claude/skills/，僅在當前項目中可用
  • 個人 Skills：~/.claude/skills/，在所有項目中可用

如果您在 .claude/commands/ 中有現有的自定義命令文件，它們會繼續工作。.claude/commands/deploy.md 中的命令文件創建 /deploy 並以與 .claude/skills/deploy/SKILL.md 中的 Skill 相同的方式工作。如果命令文件和 Skill 共享名稱，請參閱 解決共享名稱的 Skills 以了解哪一個運行。SDK 從與 Skills 相同的兩個範圍加載 .claude/commands/ 和 ~/.claude/commands/ 文件。請參閱 使用 Skills 擴展 Claude 以了解兩種工件形式的完整指南。

創建並分派您的第一個 Skill

要查看完整流程，請創建 .claude/skills/security-check/SKILL.md：

---
name: security-check
description: Run a security vulnerability scan
---

Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations

文件存在後，Skill 可通過 SDK 使用。Claude 在請求與其描述匹配時調用它，您可以直接分派它：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "/security-check",
options: { maxTurns: 10 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

成功的運行以 success 結果結束，其文本包含掃描發現。針對具有植入問題的小型 Express 應用程式，結果文本開始於：

**Security scan of `app.js` — 4 findings (most severe first):**

1. **SQL Injection** (line 8) — `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
...

Skill 的名稱也出現在初始化消息的 slash_commands 陣列中。

為 Skills 預先批准工具

Skills 使用會話的工具運行。下面的示例使用 allowedTools（Python 中的 allowed_tools）預先批准 Read、Grep 和 Glob，因此 Claude 可以在運行 security-check Skill 時檢查文件，而無需停止以獲得批准：

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
setting_sources=["user", "project"],  # Load skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)


async def main():
async for message in query(prompt="Check this project for security issues", options=options):
print(message)


asyncio.run(main())

在流中，Skill 調用顯示為 Skill 工具使用，後跟對項目文件的 Read 調用。運行以 success 結果結束，其文本包含發現。

該列表預先批准命名的工具，而不是限制其他工具。有關完整的權限流程，包括權限模式和 canUseTool 回調，請參閱 權限。

疑難排解

找不到 Skills

檢查 settingSources 設定：SDK 透過 user 和 project 設定來源探索 skills。如果您明確設定 settingSources/setting_sources 並省略這些來源，SDK 不會載入 skills：

# Skills 未載入：setting_sources 排除了 user 和 project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills 已載入：user 和 project 來源已包含
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
)

如需了解每個來源載入的 skill 目錄，請參閱檔案系統來源表。如需更多關於 settingSources/setting_sources 的詳細資訊，請參閱 TypeScript SDK 參考或 Python SDK 參考。

檢查工作目錄：SDK 從 cwd 選項中的 .claude/skills/ 以及每個父目錄（直到儲存庫根目錄）載入 skills。確保 cwd 指向包含 .claude/skills/ 的目錄或其下方目錄，且在同一個儲存庫內：

# 確保您的 cwd 指向包含 .claude/skills/ 的目錄
options = ClaudeAgentOptions(
cwd="/path/to/project",  # .claude/skills/ 在此或在父目錄中
setting_sources=["user", "project"],  # 從這些來源載入 skills
skills="all",
)

請參閱使用 Agent SDK 的 Skills 以了解完整的模式。

驗證檔案系統位置：

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

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

Skill 未被使用

檢查 skills 選項：如果您傳遞了 skills 清單，請確認 skill 的名稱已包含在內。當 Claude 嘗試叫用未列出的 skill 時，Skill 工具會傳回 Skill <name> is not in this session's skills allowlist。將名稱新增到您的清單中，或透過在提示中傳送 /<name> 直接分派 skill，這樣無需列出即可運作。

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

無效的 skill 名稱錯誤

當您 skills 清單中的名稱無法作為確切的 skill 名稱時，query() 會在啟動 Claude Code 程序之前拒絕該清單。觸發拒絕的名稱包括：

  • 空名稱
  • 包含括號、逗號或控制字元的名稱
  • 用空白字元填充的名稱
  • 萬用字元形式，例如裸露的 * 或 :* 後綴

每個 SDK 以不同的方式呈現拒絕：

TypeScript SDK 會擲出 Error，說明項目違反的規則。例如，skills: ["docs:*"] 會擲出：

Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.

空名稱會報告 Skill names must be non-empty strings.

在 TypeScript Agent SDK 0.3.221 之前，SDK 未執行此檢查。

其他疑難排解

如需一般 skills 疑難排解，例如 YAML 語法錯誤和偵錯，請參閱 Claude Code skills 疑難排解部分。

後續步驟

Claude Code Skills 指南 涵蓋了深入的編寫。其指導適用於 SDK 會話。從這些部分開始：