# 编写 Agent Skill

用一个 SKILL.md 定义触发条件、执行步骤与交付检查。

## 从一个入口文件开始

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

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

## 导入和验证

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

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

## 维护技能

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

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