{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：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 概述](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)。

## 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。

<Note>
  Skills 通过文件系统设置来源发现。使用默认 `query()` 选项时，SDK 加载用户和项目来源，因此 `~/.claude/skills/`、`<cwd>/.claude/skills/` 以及 `<cwd>` 到仓库根目录的任何父目录中的 `.claude/skills/` 中的 skills 都可用。如果您显式设置 `settingSources`，请包含 `'user'` 或 `'project'` 以保持 skill 发现，或使用 [`plugins` 选项](/en/agent-sdk/plugins)从特定路径加载 skills。
</Note>

## 在 SDK 中使用 Skills

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

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

<CodeGroup>
  ```python Python theme={null}
  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 TypeScript theme={null}
  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);
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  options = ClaudeAgentOptions(skills=["pdf", "docx"])
  ```

  ```typescript TypeScript theme={null}
  const options = { skills: ["pdf", "docx"] };
  ```
</CodeGroup>

`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。

**示例目录结构**：

```bash theme={null}
.claude/skills/processing-pdfs/
└── SKILL.md
```

有关创建 Skills 的完整指导，包括 SKILL.md 结构、多文件 Skills 和示例，请参阅：

* [Claude Code 中的 Agent Skills](/en/skills)：完整指南和示例
* [Agent Skills 最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)：编写指南和命名约定

## 工具限制

<Note>
  SKILL.md 中的 `allowed-tools` frontmatter 字段仅在直接使用 Claude Code CLI 时支持。**通过 SDK 使用 Skills 时不适用**。

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

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

<Note>
  以下代码片段假设使用第一个示例中的导入语句。
</Note>

<CodeGroup>
  ```python Python theme={null}
  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 TypeScript theme={null}
  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);
  }
  ```
</CodeGroup>

## 发现可用 Skills

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

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

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

## 测试 Skills

通过询问匹配其描述的问题来测试 Skills：

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  }
  ```
</CodeGroup>

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

## 故障排除

### Skills 未找到

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

<CodeGroup>
  ```python Python theme={null}
  # 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 TypeScript theme={null}
  // 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"
  };
  ```
</CodeGroup>

有关 `settingSources`/`setting_sources` 的更多详情，请参阅 [TypeScript SDK 参考](/en/agent-sdk/typescript#settingsource)或 [Python SDK 参考](/en/agent-sdk/python#settingsource)。

**检查工作目录**：SDK 从 `cwd` 选项中的 `.claude/skills/` 以及到仓库根目录的每个父目录中的 `.claude/skills/` 加载 Skills。确保 `cwd` 指向包含 `.claude/skills/` 的目录或其下级目录，在同一仓库内：

<CodeGroup>
  ```python Python theme={null}
  # 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",
  )
  ```

  ```typescript TypeScript theme={null}
  // 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"
  };
  ```
</CodeGroup>

有关完整模式，请参阅上面的"在 SDK 中使用 Skills"部分。

**验证文件系统位置**：

```bash theme={null}
# Check project Skills
ls .claude/skills/*/SKILL.md

# Check personal Skills
ls ~/.claude/skills/*/SKILL.md
```

### Skill 未被使用

**检查 `skills` 选项**：如果您传递了 `skills` 列表，请确认 skill 的名称已包含。传递 `[]` 会禁用所有 skills。

**检查描述**：确保它具体且包含相关关键词。有关编写有效描述的指导，请参阅 [Agent Skills 最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#writing-effective-descriptions)。

### 其他故障排除

有关一般 Skills 故障排除（YAML 语法、调试等），请参阅 [Claude Code Skills 故障排除部分](/en/skills#troubleshooting)。

## 相关文档

### Skills 指南

* [Claude Code 中的 Agent Skills](/en/skills)：完整的 Skills 指南，包含创建、示例和故障排除
* [Agent Skills 概述](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)：概念概述、优势和架构
* [Agent Skills 最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)：有效 Skills 的编写指南
* [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction)：示例 Skills 和模板

### SDK 资源

* [SDK 中的子智能体](/en/agent-sdk/subagents)：类似的基于文件系统的智能体，具有编程式选项
* [SDK 中的斜杠命令](/en/agent-sdk/slash-commands)：用户调用的命令
* [SDK 概述](/en/agent-sdk/overview)：通用 SDK 概念
* [TypeScript SDK 参考](/en/agent-sdk/typescript)：完整的 API 文档
* [Python SDK 参考](/en/agent-sdk/python)：完整的 API 文档