第 5 章 · 01 Agent Skill

第 5 章 · 01 Agent Skill

本节摘要:把 OCR 注册为可调用的 skill,使 agent 框架能以正确的参数、前置检查与分级标准调用它——无需你在调用侧重新推导这些。本节讲清三件事:仓库里的 SKILL manifest 是什么、两种安装方式(npx skills add 推荐 / 手动复制到 ~/.claude/skills 全局)、以及 SKILL.md 作为 prompt 让 agent 自动执行的七步工作流(前置检查 → 自动安装 CLI → 无 LLM 配置则停下询问 → 提取背景 → 运行评审 → High/Medium/Low 分级 → 按需修复)。读完你能在任何尊重 skills 约定的编码 agent 里一键接入 OCR。

内容来源:原项目中文文档 pages/src/content/docs/zh/integrations/agent-skill.md,套用体系化模板改写。

学习目标

阅读完本节,你应当能够:

1. 说明 SKILL manifest 的定位(把 OCR 声明为可调用 skill,含前置检查、调用流程、分级标准)。
2. 用 npx skills add 或手动复制两种方式安装 skill。
3. 描述 SKILL.md 触发的七步工作流(前置检查 → 安装 → 配置 → 背景 → 评审 → 分级 → 修复)。
4. 区分 Agent Skill 与本章 Claude Code 插件一节的默认行为差异(修复前先询问)。
5. 把 skill 接入 Anthropic Agent SDK 与其他 agent 框架。

一、仓库里有什么

仓库在 skills/open-code-review/SKILL.md 提供 SKILL manifest。它把 OCR 声明为可调用 skill,含:

• 前置检查——which ocr + ocr llm test。
• 调用工作流——按用户意图选 ocr review 参数。
• 评论分级标准——High / Medium / Low。

二、安装

方式 1:npx skills add(推荐)

在希望 skill 可用的项目内运行:

npx skills add alibaba/open-code-review --skill open-code-review
​

这从 skills registry 拉取 manifest 并放入项目,使任何尊重 skills 约定的编码 agent 在下次调用时加载它。重新运行该命令以更新 skill 到最新版本。

⚠️ 注意·前置条件:首次运行时 skill 会自行安装 ocr CLI(通过 npm install -g @alibaba-group/open-code-review),前提是二进制不在 PATH 上。你确实需要预先配置好 LLM;skill 无法替你完成,会停下来询问。配置方法见第 2 章配置一节。

方式 2:手动复制(系统级)

若想全局安装 skill 而非按项目,把文件夹复制进你的 skills 目录:

mkdir -p ~/.claude/skills
cp -R /path/to/open-code-review/skills/open-code-review ~/.claude/skills/
​

这使 skill 在机器上每个项目可用。

三、skill 做什么:七步工作流

SKILL.md 是一个 prompt:当调用方 agent 加载它时,由 agent 自身执行步骤。一次完整的 /open-code-review(或等价)请求流程如下展开:

1. 前置检查。 运行 which ocr 确认 CLI 在 PATH 上,再 ocr llm test 确认 LLM 可达。
2. CLI 缺失则自动安装。 若 which ocr 报告 NOT INSTALLED,agent 运行 npm install -g @alibaba-group/open-code-review 并继续。不提示用户——这被视为常规设置步骤。
3. 无 LLM 配置则停下询问。 若 ocr llm test 失败,agent 不会编造凭证。它向用户展示两种受支持的方式(环境变量或 ocr config set …)并等待用户提供 API key。
4. 提取业务上下文。 检查评审目标(commit、分支、工作副本)并生成一个简短的 --background 字符串。
5. 运行评审。 调用 ocr review --audience agent --background "…" [--commit | --from/--to],根据用户是要评审工作副本、特定 commit 还是分支区间来选择参数。
6. 分类与报告。 用 SKILL.md 中的标准把 JSON 评论分为 High / Medium / Low(bug 与安全问题为 High;吹毛求疵与疑似误报被静默丢弃),再渲染 Markdown 摘要。
7. 按需修复。 若用户说「评审并修复」(或类似),对 High/Medium 项内联应用安全修复;否则修改代码前先询问。

┌─────────────────────────────────────────────────────────────────┐
│  ① which ocr + ocr llm test   ──前置检查                          │
│  ② 缺 CLI → npm install -g    ──自动安装(不提示)                │
│  ③ llm test 失败 → 停下询问    ──绝不编造凭证                      │
│  ④ 生成 --background          ──提取业务上下文                    │
│  ⑤ ocr review --audience agent──运行评审                          │
│  ⑥ High/Medium/Low 分级       ──疑似误报静默丢弃                   │
│  ⑦ 用户要求才修复             ──默认改代码前先询问                 │
└─────────────────────────────────────────────────────────────────┘
​

💡 技巧:如想收紧上述任一项(比如把默认行为改为修复前总先询问,或反过来默认修复),编辑你本地副本——SKILL.md 是纯 markdown,改了即生效。完整 prompt(确切分级标准、输出模板、注意事项)位于 skills/open-code-review/SKILL.md。

四、Anthropic Agent SDK

把你的 SDK init 指向已安装的 skill 路径:

from anthropic_agent_sdk import Agent

agent = Agent(
    skill_paths=["/path/to/open-code-review/skills/open-code-review"],
)

agent.run("Review my staged changes — focus on race conditions.")
​

SDK 加载 SKILL.md prompt,由 agent 执行上述七步工作流——包括 npm install 回退与无 LLM 配置时提示输入凭证的步骤。

五、其他 agent 框架

任何有「注册外部 skill」接口的框架都能摄入 SKILL.md——它只是带 frontmatter 的 markdown。若你的框架期望不同 schema,markdown 正文仍可用作 prompt 模板。

六、与 Claude Code 插件的差异

⚠️ 注意:两者底层都调用同一个 ocr CLI,差异只在默认修复策略。想「评审并自动应用修复」用 Claude Code 插件;想「先看再决定」用 Agent Skill。

本节要点回顾

1. SKILL manifest:把 OCR 声明为可调用 skill,含前置检查、调用流程、High/Medium/Low 分级标准。
2. 两种安装:npx skills add(项目级,推荐)/ 手动复制到 ~/.claude/skills(全局)。
3. 七步工作流:前置检查 → 自动装 CLI → 无配置则停下询问 → 提取 --background → ocr review --audience agent → 分级 → 按需修复。
4. 绝不编造凭证:LLM 配置缺失时停下询问用户,展示两种受支持方式。
5. 疑似误报静默丢弃:吹毛求疵与缺上下文的评论不出现在摘要里。
6. 默认修复策略:Agent Skill 改代码前先询问(与 Claude Code 插件的默认自动修复相反)。
7. SDK 接入:skill_paths=[...] 指向已安装 skill 即可;其他框架摄入带 frontmatter 的 markdown。

Agent Skill 讲完了。下一节看 Claude Code 插件——同一底层 CLI 的 slash-command 版本,默认自动修复,适合「评审并清理」工作流。