技能

"Skills"（技能）是可复用的、基于文件系统的资源，为您的智能体提供特定领域的专业知识：工作流程、上下文和最佳实践，将通用智能体转变为专家。您添加的每个技能都会对会话的上下文窗口产生一定的开销，因为它会添加帮助模型使用该技能的指令和元数据。请参阅 Agent Skills 概述了解更多信息。

技能通过两种方式提供给您的智能体：通过智能体的 skills 数组附加，或从挂载到会话的 GitHub 仓库加载。附加的技能分为两种类型。所有技能的工作方式相同：当技能与任务相关时，您的智能体会自动调用它们。

• **Anthropic 预构建技能：**常见的文档任务，例如 PowerPoint、Excel、Word 和 PDF 处理（pptx、xlsx、docx、pdf）。
• **自定义技能：**您编写并上传到工作区的技能。

要了解如何编写自定义技能，请参阅 Agent Skills 和技能编写最佳实践。要将自定义技能上传到您的工作区，请参阅创建自定义技能。



创建自定义技能

自定义技能是一个包含 SKILL.md 文件以及任何支持文件的目录，以 zip 压缩包或单个文件的形式上传到您的工作区。创建技能后会返回 skill_* ID，您在将其附加到智能体时需要引用该 ID。Anthropic 预构建技能已在每个工作区中可用，无需执行此步骤。如果只使用预构建技能，请跳至将技能附加到智能体。

Skills API 不需要 beta 标头。cURL 示例仍会发送 anthropic-beta: skills-2025-10-02，CLI 和 SDK 的 beta 命令会自动添加该标头；包含该标头的请求仍可正常工作，无需更改。

这些示例省略了可选的 display_title 字段，因此技能的标题将从 SKILL.md 派生。显式传递的 display_title 在您工作区的自定义技能中必须是唯一的。

ant beta:skills create \
  --file example_skill.zip

要列出、检索、删除自定义技能以及管理其版本，请参阅管理自定义技能。有关完整的请求和响应架构，请参阅创建技能 API 参考。技能包直接上传到 Skills API，而不是通过 Files API。



将技能附加到智能体

在创建智能体时附加技能。每个会话最多支持 500 个技能，该数量按会话中所有智能体去重后的技能集合计算（请参阅多智能体编排）。

skills 数组中的每个条目使用以下字段：

ant beta:agents create < agent.yaml

name: Financial Analyst
model: claude-opus-5
system: You are a financial analysis agent.
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
    version: latest



从 GitHub 仓库加载技能

技能也可以存放在您的代码库中。当会话通过 github_repository 资源挂载仓库时，会在会话启动时扫描仓库根目录下的 .claude/skills 目录，其中找到的每个技能都会对智能体可用。无需上传，也无需在智能体的 skills 数组中添加条目。智能体可以看到每个已发现技能的名称、描述以及在沙箱中的路径，并在任务匹配时读取该技能的 SKILL.md，包括该技能附带的任何脚本和资源。技能发现依赖于智能体工具集中的 read 工具，该工具默认启用；禁用了 read 的智能体不会加载仓库技能。

技能发现会在仓库根目录下恰好一层深的位置 .claude/skills/<skill-name>/SKILL.md 查找技能：

• your-repo/
  • .claude/
    • skills/
      • code-review/
        • SKILL.md
      • release-process/
        • SKILL.md
        • scripts/
          • run_checks.sh
  • src/

不符合此布局的位置在会话启动时不会被发现：

• .claude/skills/SKILL.md：没有技能目录包裹的 SKILL.md
• .claude/skills/tools/code-review/SKILL.md：嵌套深度超过一层目录
• skills/code-review/SKILL.md：位于 .claude 之外的 skills 目录

位于仓库其他位置的 .claude/skills 目录（例如在某个包的子目录内）不会在会话启动时被公告；当智能体读取该子树下的文件时，这些技能仍可能被发现。

仓库技能使用与您上传的自定义技能相同的 SKILL.md 格式。有关格式和编写指南，请参阅 Agent Skills 和技能编写最佳实践。

要从仓库加载技能，请创建一个挂载该仓库的会话。这与访问 GitHub 中展示的请求相同；mount_path 是可选的，默认为 /workspace/<repo-name>：

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --transform id --raw-output <<'EOF'
resources:
  - type: github_repository
    url: https://github.com/org/repo
    mount_path: /workspace/repo
    authorization_token: ghp_your_github_token
EOF
)

对于私有仓库，资源的 authorization_token 必须具有访问该仓库的权限。这与任何仓库挂载所使用的个人访问令牌流程相同；请参阅访问 GitHub。

已发现的技能遵循仓库的检出状态：如果资源设置了 checkout 分支或提交，则使用该分支或提交，否则使用仓库的默认分支。扫描仅在会话启动时运行一次。会话期间推送的提交不会被拾取；要加载更新后的技能，请启动新会话。

仓库技能可与通过智能体 skills 数组附加的技能一起使用。如果某个仓库技能与已附加的技能同名，或与另一个已挂载仓库中的技能同名，则两者都可用；每个技能都会以其各自的路径进行公告。



后续步骤