文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

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：

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

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

在 SDK 中使用 Skills

在 query() 上设置 skills 选项以控制会话可用的 Skills。省略时，发现的 Skills 被启用且 Skill 工具可用，与 CLI 行为匹配。传递 "all" 以启用每个发现的 Skill，传递 Skill 名称列表以仅启用这些，或传递 [] 以禁用所有。当您设置 skills 时，SDK 自动启用 Skill 工具，因此您无需在 allowedTools 中列出它。

配置后，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())

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。

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

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 最佳实践：编写指南和命名约定

工具限制

要在 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)

for await (const message of query({
  prompt: "Analyze the codebase structure",
  options: {
    settingSources: ["user", "project"], // Load Skills from filesystem
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "dontAsk" // Deny anything not in allowedTools
  }
})) {
  console.log(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)

for await (const message of query({
  prompt: "What Skills are available?",
  options: {
    settingSources: ["user", "project"], // Load Skills from filesystem
    skills: "all"
  }
})) {
  console.log(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)

for await (const message of query({
  prompt: "Extract text from invoice.pdf",
  options: {
    cwd: "/path/to/project",
    settingSources: ["user", "project"], // Load Skills from filesystem
    skills: "all",
    allowedTools: ["Read", "Bash"]
  }
})) {
  console.log(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",
)

// 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"
};

有关 settingSources/setting_sources 的更多详情，请参阅 TypeScript SDK 参考或 Python SDK 参考。

检查工作目录：SDK 从 cwd 选项中的 .claude/skills/ 以及到仓库根目录的每个父目录中的 .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",
)

// Ensure your cwd points to the directory containing .claude/skills/
const options = {
  cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
  settingSources: ["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 指南

• Claude Code 中的 Agent Skills：完整的 Skills 指南，包含创建、示例和故障排除
• Agent Skills 概述：概念概述、优势和架构
• Agent Skills 最佳实践：有效 Skills 的编写指南
• Agent Skills Cookbook：示例 Skills 和模板

SDK 资源

• SDK 中的子智能体：类似的基于文件系统的智能体，具有编程式选项
• SDK 中的斜杠命令：用户调用的命令
• SDK 概述：通用 SDK 概念
• TypeScript SDK 参考：完整的 API 文档
• Python SDK 参考：完整的 API 文档