编写 Agent Skill

从一个入口文件开始

一个 Agent Skill 至少包含 SKILL.md。将一项经过验证的方法写入入口文件；需要脚本、模板或参考资料时，再放入同一目录并从入口引用。

report-review/
  SKILL.md
  references/       可选的参考资料
  scripts/          可选的执行脚本
  templates/        可选的交付模板

最小示例

下面是一个普通 Agent 技能，可保存为 report-review/SKILL.md 后打包导入。

---
name: report-review
description: 用户要求复核报告草稿时使用，检查事实依据、结构与待确认事项。
---

## 适用范围

用于已有草稿的复核。没有草稿时先请用户提供材料。

## 执行步骤

1. 阅读草稿和用户提供的来源。
2. 列出缺少依据或相互冲突的结论。
3. 检查章节顺序、重复内容和遗漏问题。
4. 保存 review.md，保留原稿不动。

## 交付检查

每条意见写明对应段落、问题和建议。无法核实的事实标为待确认。
不发送消息，不发布报告，不自行补造来源。

写清触发条件

description 应说明适用的请求类型。正文区分输入、步骤、交付与停止条件。技能应遵守用户限定的任务范围，所需外部账号仍需单独授权。

引用附件使用相对于技能目录的路径，避免作者电脑上的绝对路径。脚本需要说明运行环境、输入和输出，缺少依赖时应给出可执行的处理办法。

入口字段与正文分别负责什么

Nexus 的技能目录会读取名称、描述、范围及展示元数据。来自其他产品的专有 frontmatter 不应直接视为 Nexus 的控制选项，尤其不能用一个未经支持的字段代替权限配置。

将检查表放到支持文件

方法有较长检查表时，把它保存为 references/checklist.md，在入口中说明什么时候读取它。下面是教学内容，可按你的报告类型调整。

# 报告复核清单

- 数字是否能找到来源，单位与统计时间是否一致。
- 原文未说明的负责人和日期是否保留为待确认。
- 建议是否被误写成已经通过的决定。
- 引用的文件是否为当前有效版本。

在 SKILL.md 的步骤中增加“读取 references/checklist.md，按其中的检查项复核”。相对路径应从技能目录出发，不能使用作者电脑中的个人路径。

准备一组能够发现错误的材料

保存一份教学原文和草稿，故意放入一个可定位的错误。

原文
测试环境尚未准备好，负责人未确定。

待复核草稿
小林将在周五完成测试环境准备。

运行报告复核技能后，review.md 应指出负责人和截止日期都没有原文依据，并保留原稿。只有一句“写得不错”不满足检查要求。

再删除原文测试一次。技能应说明缺少依据，不能继续宣称草稿事实已核实。最后用不相关请求测试，确认不会强行生成报告复核文件。

脚本与外部依赖

需要脚本时，在正文说明执行程序、输入文件、输出和失败处理。只有文本检查表的技能不必添加脚本目录。

脚本缺少依赖时，应报告缺少的程序和执行阶段；服务未授权时，使用连接器配置入口。技能安装成功不能证明这两类依赖已经准备好。

导入和验证

通过技能导入使用 Git HTTPS 地址或 ZIP。为测试 Agent 启用后，至少验证一次正常输入、一次缺少材料，以及一次不适用的请求。

检查真实文件是否产生、原稿是否保留、未确认事实是否被正确标注。以执行结果判断技能是否生效。

维护技能

当流程变化时更新说明与引用文件，重新测试受到影响的步骤。凭据留在 Provider、连接器或环境配置中，不能打包进技能仓库。

需要主持、成员交接和公开/私下协作时，使用Room Skill规定各成员的行为。