Skills

Skills 是以 SKILL.md 文件形式定义的专项能力，存放在 .claude/skills/ 目录下。Claude 根据上下文自主判断何时调用，也可通过 /skill-name 显式触发。与子 Agent 不同，Skills 必须以文件系统形式存在，SDK 不提供编程式注册 API。

核心机制

加载机制：Skills 通过 settingSources 发现。包含 "project" 时加载 .claude/skills/，包含 "user" 时加载 ~/.claude/skills/。

skills 选项控制可用范围：

• 省略：与 CLI 行为一致，发现的 Skills 默认启用
• "all"：启用所有发现的 Skills
• ["pdf", "docx"]：只启用指定名称的 Skills
• []：禁用所有 Skills

自动启用 Skill 工具：设置 skills 选项后，SDK 自动将 Skill 工具加入可用工具，无需在 allowedTools 中额外列出。

Skills 是上下文过滤器，不是沙箱：未列出的 Skills 对模型隐藏，但文件仍在磁盘上，可通过 Read/Bash 访问。

关键细节

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # 必须包含对应来源
    skills="all",                          # 或指定名称列表
    allowed_tools=["Read", "Write", "Bash"],
)

Skill 目录结构：

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

Skill 位置：

• 项目级：.claude/skills/（通过 git 与团队共享）
• 用户级：~/.claude/skills/（跨项目个人 Skills）
• 插件 Skills：通过 plugins 加载

常见问题：

• Skills 未找到：检查 settingSources 是否包含对应来源，检查 cwd 是否指向包含 .claude/skills/ 的目录
• Skills 未被调用：检查 skills 选项是否包含该 Skill 名称，检查 SKILL.md 的 description 是否清晰

与其他概念的关联

• claude-code-features - settingSources 控制 Skills 加载
• plugins - 插件提供的 Skills
• slash-commands - Skills 也可通过 /skill-name 显式调用
• subagents - 编程式定义的专项 Agent（vs 文件系统 Skills）

实践要点

• Skills 的 description 字段决定 Claude 何时自动调用，要包含触发关键词
• 在 AgentDefinition 的 skills 字段中列出 Skill 名称，可为子 Agent 预加载特定 Skills
• 插件提供的 Skills 使用 plugin:skill-name 格式引用
• SDK 中 SKILL.md 的 allowed-tools frontmatter 字段无效，工具控制通过 allowedTools 选项实现