技能

"Skills"（技能）是可复用的、基于文件系统的资源，可为您的智能体提供特定领域的专业能力：工作流、上下文和最佳实践，将通用智能体转变为专家。您添加的每个技能都会对会话的 "context window"（上下文窗口）产生少量开销，因为它会添加帮助模型使用该技能的指令和元数据。请在 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 标头。仍然发送 anthropic-beta: skills-2025-10-02 的请求会继续正常工作，并返回早期的响应字段。

这些示例省略了可选的 display_name 字段，因此技能的显示名称派生自 SKILL.md 中的 name 字段。显式指定的 display_name 最多可包含 255 个字符，并且在您的工作区内不需要唯一。

ant skills create \
  --file example_skill.zip

要列出、检索、删除自定义技能以及管理其版本，请参阅管理自定义技能。有关完整的请求和响应模式，请参阅 Create Skill 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 数组附加的技能一起使用。如果某个仓库技能与某个已附加技能同名，或与来自另一个已挂载仓库的技能同名，则两者都可用；每个技能都会以各自的路径公布。



后续步骤