加粗样式

1. 概要

1.1 Skill 解决什么问题

一个团队做发布评审，每次都要提醒 AI 查变更、核对测试结果、找出迁移风险，再按约定格式给出结论。说明散在聊天里，换一个人或新开会话，就得再讲一遍。

Agent Skills 把这些经常重复的做法放进一个目录。目录里的 SKILL.md 告诉 Agent 什么时候用这套流程、需要看什么、最后要交付什么。流程如果还依赖检查脚本、输出模板或领域说明，也可以随目录一起维护。Agent Skills 规范

1.2 anthropics/skills 仓库里有什么

这是 Anthropic 公开的 Skills 实现和示例仓库。里面有文档处理、网页测试、MCP 服务开发等示例，也提供编写 Skill 的模板。复用代码或素材时，可以从对应目录的许可证开始核对。仓库说明

以 webapp-testing 为例，SKILL.md 描述怎样选择测试路径，scripts/with_server.py 负责启动和管理本地服务，examples/ 放 Playwright 的用法示例。流程、工具和示例放在一起，读者可以顺着一次实际测试理解整个目录。网页测试 Skill

2. 如何实现

2.1 先写一个只做发布评审的 Skill

先从团队已经有明确做法的任务开始。下面这个例子只需要一个文件。若要在本地 Claude Code 项目里使用，可以把文件保存为 .claude/skills/release-review/SKILL.md。

---
name: release-review
description: 检查软件发布候选的代码变更、测试结果和回滚条件。用于上线前评审、发布检查或判断候选版本是否具备发布条件。
---

# 发布评审

1. 确认待发布版本、比较基准和目标环境。缺少关键信息时先询问。
2. 阅读变更，找出接口、配置和数据库迁移方面的影响。
3. 核对已经取得的测试结果。只有测试通过记录才能支持“已通过”的结论。
4. 说明发布前需要处理的问题，以及回滚前提。
5. 按“结论、阻塞项、验证证据、待确认事项”输出评审结果。

本流程的交付物是评审报告。执行部署和合并属于单独的操作流程。

name 和 description 是规范要求的两个字段，名称应和 Skill 目录名一致。描述里要说清具体任务和使用时机。比如“检查上线前的变更与验证证据”比“帮忙做研发”更容易匹配到正确的请求。文件格式规范

2.2 把说明、资料和脚本拆开

一开始可以只有 SKILL.md。如果团队有详细的迁移要求，再放一份 references/migration-checklist.md，并在正文里说明只有发现数据库迁移时才读它。需要固定格式的报告模板可以放到 assets/。

有些步骤适合写成脚本。比如“比较两份接口描述并列出不兼容字段”，可以交给 scripts/check-api-compat.py，让相同输入得到可以复查的结果。脚本输出差异，Agent 再结合发布范围判断这些差异是否构成阻塞。

这样修改流程时也好找。业务规则在说明里，确定的检查在脚本里，报告样式在模板里。Skill 目录结构

2.3 先让 Agent 知道有哪些 Skill，再按需加载

一个支持 Skills 的运行时通常会分三步处理。

1. 发现 Skill 时，读取名称和描述，组成目录。
2. 用户显式指定 Skill，或模型判断任务匹配时，加载 SKILL.md 正文。
3. 执行中遇到需要的资料，再读取对应文件，或通过运行时提供的工具调用脚本。

拿发布评审举例，用户问“这版能上线吗”时，Agent 才读评审步骤。它检查变更后发现没有数据库迁移，就可以跳过那份迁移清单。这种按需加载就是官方所说的渐进披露。客户端实现指南

3. 生产项目如何接入

3.1 给开发团队用，可以放进项目仓库

如果团队在本地用 Claude Code，把上面的 Skill 目录提交到仓库，成员在项目会话中可以输入 /release-review 主动调用。也可以用自然语言提需求，检查它是否能根据描述自动匹配。

如果想直接试用 Anthropic 的示例，可以在 Claude Code 内依次运行下面的命令。

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

文档类技能对应 document-skills@anthropic-agent-skills。项目内的自定义 Skill 和仓库插件是两种分发方式，可以按团队的维护习惯选择。Claude Code Skills 文档 · 仓库安装说明

3.2 后端使用 Claude API，可以在请求中指定 Skill

用 Anthropic 内置的文档类 Skill 时，后端在 Messages 请求的 container.skills 中指定 Skill，同时配置代码执行工具。下面是接到已有 Messages 请求上的配置片段，示例选择了内置的 xlsx。

{
  "container": {
    "skills": [
      {
        "type": "anthropic",
        "skill_id": "xlsx",
        "version": "latest"
      }
    ]
  },
  "tools": [
    {
      "type": "code_execution_20250825",
      "name": "code_execution"
    }
  ]
}

自定义 Skill 先通过 Skills API 创建和上传，应用请求使用 type: custom 和返回的 skill_id。试用时可以指定 latest，上线时建议固定验证过的版本。对于需要生成文件的任务，后端还要从响应中取出文件 ID，并通过 Files API 下载；长任务则按文档处理 pause_turn 和容器续接。Claude API Skills 指南

3.3 自研 Agent，可以从一个简单的加载器开始

如果已有自己的模型调用、工具执行和权限系统，可以把 Skill 当作一组按任务选择的文件。第一版做一个明确的入口就够了。比如在发布评审页面，由后端直接选择 release-review，载入正文，再按当前用户的权限提供变更与测试查询工具。业务入口已经明确时，可以省去模型自行选择 Skill 这一步。

当多个流程共用同一对话入口时，再增加自动选择。后端把当前用户有权使用的 Skill 名称和描述传给模型，模型提出选择，后端负责核对并加载。参考资料可以通过受限的读取接口按需访问，例如只接收 Skill ID 和目录内相对路径，由后端校验路径范围。

Skill 和业务工具也可以一起用。发布评审 Skill 规定应该核对哪些证据，工具负责从代码仓库和 CI 查询真实数据。是否可以读取某个项目、调用什么操作，仍由后端按当前用户授权决定。

3.4 先验证它能帮上忙，再扩大使用范围

用发布评审来试，可以准备几种有明确结果的任务。比如测试齐全的正常发布、缺少测试结果的变更、包含数据库迁移的变更，再加一个普通代码解释请求，检查会不会误触发。

保持模型、工具和输入一致，比较接入前后有没有漏掉阻塞项，报告里的结论能不能追到真实证据，再记录耗时和调用成本。发现误触发就改描述，发现有步骤经常遗漏就改正文，发现固定检查反复出错就考虑交给脚本。

接入第三方 Skill 时，先审查正文、脚本和依赖，再把通过验证的版本加入项目。生产运行时可以记录任务用到的 Skill 版本及工具调用结果，方便出问题时复现和回退。发布、写库等有副作用的动作继续走业务系统自己的授权入口。在 Claude Code 里，如果某个流程应由用户主动启动，可以加上 disable-model-invocation: true，通过斜杠命令调用。Claude Code 调用控制