# 编写 Agent Skill

编写入口与支持文件，用有已知错误的材料验证技能，并处理缺失依赖。

## 从一个入口文件开始

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

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

## 最小示例

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

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

## 适用范围

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

## 执行步骤

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

## 交付检查

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

## 写清触发条件

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

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

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

| 字段或内容 | 本例用途 |
| --- | --- |
| `name` | 技能标识，使用稳定且可区分的名称 |
| `description` | 说明什么请求适用，而非只写“提高效率” |
| `scope: room` | Room 技能的作用范围；普通 Agent 示例无需填写 |
| 正文步骤 | 阅读什么、怎样处理、保存什么 |
| 交付检查 | 如何发现错误与缺失材料 |

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

## 将检查表放到支持文件

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

```markdown
# 报告复核清单

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

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

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

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

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

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

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

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

## 脚本与外部依赖

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

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

## 导入和验证

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

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

## 维护技能

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

需要主持、成员交接和公开/私下协作时，使用[Room Skill](/docs/room-skills)规定各成员的行为。