Claude Code官方文档Agent SDKSkills

Claude Agent SDK Skills - 用 Agent Skills 扩展专门能力

使用 Claude Agent SDK 中的 Agent Skills 扩展 Claude 的专业能力。

发布于 2025年5月1日 · 阅读约 15 分钟

SDK 中的 Agent Skills

使用 Claude Agent SDK 中的 Agent Skills 扩展 Claude 的专业能力

概述

Agent Skills 通过专业能力扩展 Claude，Claude 会在相关时自动调用这些能力。Skills 被打包为 SKILL.md 文件，包含说明、描述和可选的支持资源。

有关 Skills 的全面信息，包括优势、架构和编写指南，请参阅 Agent Skills 概述。

Skills 如何与 SDK 配合使用

使用 Claude Agent SDK 时，Skills 的工作方式如下：

定义为文件系统工件：在特定目录（.claude/skills/）中创建为 SKILL.md 文件
从文件系统加载：Skills 从由 settingSources（TypeScript）或 setting_sources（Python）管理的文件系统位置加载
自动发现：加载文件系统设置后，在启动时从用户和项目目录发现 Skill 元数据；触发时加载完整内容
由模型调用：Claude 根据上下文自动选择何时使用它们
通过 skills 选项过滤：发现的 Skills 默认启用。传递 Skill 名称列表、"all" 或 [] 来控制会话中可用的 Skills

与子代理（可以通过编程方式定义）不同，Skills 必须创建为文件系统工件。SDK 不提供用于注册 Skills 的编程 API。

ℹ️ Skills 通过文件系统设置源发现。使用默认 query() 选项时，SDK 加载用户和项目源，因此 ~/.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 中列出它。

配置后，Claude 自动从文件系统发现 Skills 并在与用户请求相关时调用它们。

Python：

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())

TypeScript：

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

要仅启用特定 Skills，请传递它们的名称。名称与 SKILL.md 中的 name 字段或 Skill 的目录名称匹配。对于插件提供的 Skills，使用 plugin:skill。

Python：

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

TypeScript：

const options = { 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 和示例，请参阅：

Claude Code 中的 Agent Skills：包含示例的完整指南
Agent Skills 最佳实践：编写指南和命名约定

工具限制

ℹ️ SKILL.md 中的 allowed-tools frontmatter 字段仅在直接使用 Claude Code CLI 时受支持。通过 SDK 使用 Skills 时不适用。

使用 SDK 时，通过查询配置中的主 allowedTools 选项控制工具访问。

要在 SDK 应用程序中控制 Skills 的工具访问，使用 allowedTools 预先批准特定工具。没有 canUseTool 回调时，列表中没有的任何内容都被拒绝：

Python：

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)

TypeScript：

for await (const message of query({
  prompt: "Analyze the codebase structure",
  options: {
    settingSources: ["user", "project"],
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "dontAsk" // Deny anything not in allowedTools
  }
})) {
  console.log(message);
}

发现可用的 Skills

要查看 SDK 应用程序中可用的 Skills，只需询问 Claude：

Python：

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)

TypeScript：

for await (const message of query({
  prompt: "What Skills are available?",
  options: {
    settingSources: ["user", "project"],
    skills: "all"
  }
})) {
  console.log(message);
}

Claude 将根据您当前的工作目录和已安装的插件列出可用的 Skills。

测试 Skills

通过提出与其描述匹配的问题来测试 Skills：

Python：

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],
    skills="all",
    allowed_tools=["Read", "Bash"],
)

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

TypeScript：

for await (const message of query({
  prompt: "Extract text from invoice.pdf",
  options: {
    cwd: "/path/to/project",
    settingSources: ["user", "project"],
    skills: "all",
    allowedTools: ["Read", "Bash"]
  }
})) {
  console.log(message);
}

如果描述与您的请求匹配，Claude 会自动调用相关的 Skill。

故障排除

找不到 Skills

检查 settingSources 配置：Skills 通过 user 和 project 设置源发现。如果显式设置 settingSources/setting_sources 并省略这些源，Skills 不会加载：

Python：

# 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",
)

TypeScript：

// Skills not loaded: settingSources excludes user and project
const options = {
  settingSources: [],
  skills: "all"
};

// Skills loaded: user and project sources included
const options = {
  settingSources: ["user", "project"],
  skills: "all"
};

检查工作目录：SDK 相对于 cwd 选项加载 Skills。确保它指向包含 .claude/skills/ 的目录：

Python：

options = ClaudeAgentOptions(
    cwd="/path/to/project",  # Must contain .claude/skills/
    setting_sources=["user", "project"],  # Loads skills from these sources
    skills="all",
)

TypeScript：

const options = {
  cwd: "/path/to/project",
  settingSources: ["user", "project"],
  skills: "all"
};

验证文件系统位置：

# 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 故障排除部分。

Claude Agent SDK Skills - 用 Agent Skills 扩展专门能力

SDK 中的 Agent Skills

概述

Skills 如何与 SDK 配合使用

在 SDK 中使用 Skills

Skill 位置

创建 Skills

工具限制

发现可用的 Skills

测试 Skills

故障排除

找不到 Skills

Skill 未被使用

其他故障排除

相关文档

Skills 指南

SDK 资源