通过 skills 选项控制哪些 Skills 对会话可用，通过 setting_sources（Python）或 settingSources（TypeScript）配置从文件系统加载技能。当 skills 选项省略时，自动加载并启用所有发现的技能。SKILL.md 文件需放在 .claude/skills/ 目录下；使用 ls .claude/skills/*/SKILL.md 检查文件是否存在。注意：SKILL.md 中的 allowed-tools 字段在 SDK 中不生效，工具权限需通过主配置中的 allowedTools 控制。

Claude Code 技能模块 SKILL.md 配置指南

概述

Agent Skills 为 Claude 提供专业化能力，Claude 会根据上下文自动调用。技能被打包为 SKILL.md 文件，包含指令、描述和可选的支持资源。

Skills 在 SDK 中的工作方式

在 Claude Agent SDK 中，Skills：

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

与可通过编程方式定义的子代理不同，技能必须创建为文件系统工件。SDK 不提供注册技能的程序化 API。

技能通过文件系统设置源发现。使用默认 query() 选项时，SDK 会加载用户和项目源，因此 ~/.claude/skills/、<cwd>/.claude/skills/ 以及 <cwd> 任何父目录（直到仓库根目录）中的技能都可用。如果你显式设置了 settingSources，请包含 'user' 或 'project' 以保留技能发现，或使用 plugins 选项 从特定路径加载技能。

怎么用 SDK 配置 Skills

在 query() 上设置 skills 选项，控制哪些 Skills 对会话可用。省略时，发现到的 Skills 会被启用，Skill 工具可用，与 CLI 行为一致。传入 "all" 启用每个发现的技能，传入技能名称列表仅启用列表中技能，传入 [] 全部禁用。设置 skills 后，SDK 会自动启用 Skill 工具，因此无需在 allowedTools 中列出。

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        cwd="/path/to/project",  # 包含 .claude/skills/ 的项目目录
        setting_sources=["user", "project"],  # 从文件系统加载 Skills
        skills="all",  # 启用所有发现到的技能
        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", // 包含 .claude/skills/ 的项目目录
    settingSources: ["user", "project"], // 从文件系统加载 Skills
    skills: "all", // 启用所有发现到的技能
    allowedTools: ["Read", "Write", "Bash"]
  }
})) {
  console.log(message);
}

仅启用特定技能时，传入它们的名称。名称匹配 SKILL.md 中的 name 字段或技能目录名。对于插件提供的技能，使用 plugin:skill 格式。

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

const options = { skills: ["pdf", "docx"] };

skills 选项是一个上下文过滤器，不是沙箱。未列出的技能对模型隐藏，并被 Skill 工具拒绝，但其文件仍保留在磁盘上，可通过 Read 和 Bash 访问。

技能位置

Skill 加载自文件系统目录，基于你的 settingSources/setting_sources 配置：

• 项目技能（.claude/skills/）：通过 git 与团队共享——当 setting_sources 包含 "project" 时加载
• 用户技能（~/.claude/skills/）：跨所有项目的个人技能——当 setting_sources 包含 "user" 时加载
• 插件技能：与已安装的 Claude Code 插件捆绑提供

怎么创建 SKILL.md 文件

技能被定义为包含 SKILL.md 文件的目录，该文件具有 YAML 格式 frontmatter 和 Markdown 内容。description 字段决定了 Claude 何时调用你的技能。

示例目录结构：

.claude/skills/processing-pdfs/
└── SKILL.md

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

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

工具限制

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

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

要控制在 SDK 应用中对技能的工具访问，使用 allowedTools 预审批特定工具。没有 canUseTool 回调时，未在列表中出现的工具都会被拒绝：

以下代码片段假定已导入第一个示例中的语句。

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # 从文件系统加载 Skills
    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"], // 从文件系统加载 Skills
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "dontAsk" // 拒绝任何不在 allowedTools 中的工具
  }
})) {
  console.log(message);
}

怎么查看可用的 Skills

要查看 SDK 应用中有哪些技能可用，直接询问 Claude：

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # 从文件系统加载 Skills
    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"], // 从文件系统加载 Skills
    skills: "all"
  }
})) {
  console.log(message);
}

Claude 会根据当前工作目录和已安装的插件列出可用的技能。

怎么测试 Skills 是否正常

通过询问与技能描述匹配的问题来测试：

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # 从文件系统加载 Skills
    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"], // 从文件系统加载 Skills
    skills: "all",
    allowedTools: ["Read", "Bash"]
  }
})) {
  console.log(message);
}

如果描述与请求匹配，Claude 会自动调用相关技能。

故障排查

Skills 加载失败怎么办

检查 settingSources 配置：技能通过 user 和 project 设置源发现。如果显式设置了 settingSources/setting_sources 并遗漏了这些源，技能不会加载：

# Skills 不加载：setting_sources 排除了 user 和 project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills 加载：包含 user 和 project 源
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    skills="all",
)

// Skills 不加载：settingSources 排除了 user 和 project
const options = {
  settingSources: [],
  skills: "all"
};

// Skills 加载：包含 user 和 project 源
const options = {
  settingSources: ["user", "project"],
  skills: "all"
};

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

检查工作目录：SDK 从 cwd 选项中的 .claude/skills/ 以及每个父目录（直到仓库根目录）加载技能。确保 cwd 指向包含 .claude/skills/ 的目录或其下的目录，且在同一仓库中：

# 确保 cwd 指向包含 .claude/skills/ 的目录
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # .claude/skills/ 在此处或其父目录中
    setting_sources=["user", "project"],  # 从这些源加载技能
    skills="all",
)

// 确保 cwd 指向包含 .claude/skills/ 的目录
const options = {
  cwd: "/path/to/project", // .claude/skills/ 在此处或其父目录中
  settingSources: ["user", "project"], // 从这些源加载技能
  skills: "all"
};

查看上方"怎么用 SDK 配置 Skills"部分了解完整模式。

验证文件系统位置：

# 检查项目技能
ls .claude/skills/*/SKILL.md

# 检查个人技能
ls ~/.claude/skills/*/SKILL.md

Skill 不被调用怎么排查

检查 skills 选项：如果你传入了 skills 列表，确认技能名称已包含在内。传入 [] 会禁用所有技能。

检查描述：确保描述具体且包含相关关键词。请参阅 Agent Skills 最佳实践 获取编写有效描述的指导。

其他常见问题

有关 Skills 的通用故障排查（YAML 语法、调试等），请参阅 Claude Code Skills 故障排查部分。

相关文档

Skills 指南

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

SDK 资源

• SDK 中的子代理：类似的文件系统代理，具有编程选项
• SDK 中的斜杠命令：用户调用的命令
• SDK 概述：一般 SDK 概念
• TypeScript SDK 参考：完整 API 文档
• Python SDK 参考：完整 API 文档

常见问题

Skills 报 'not found' 怎么办？

检查 setting_sources（Python）或 settingSources（TypeScript）是否包含 "user" 和 "project"。如果显式设置并遗漏了这些源，技能不会加载。同时确认 cwd 指向包含 .claude/skills/ 的目录或其父目录。

怎么限制 Skills 使用的工具？

通过主 query() 配置中的 allowedTools 选项控制。注意：SKILL.md 中的 allowed-tools 字段在 SDK 中不生效。

为什么我定义了一个 Skill，但 Claude 不调用它？

确认 skills 选项中包含该技能名称（传入 "all" 可启用所有技能）。同时检查 SKILL.md 的 description 是否足够具体，包含它能处理的场景关键词。