Skill

Skill 快速开始

做一个小 Skill 文件夹，写好 SKILL.md，再测试 Agent 能不能正确激活它。

1. 创建文件夹

如果你想做一个多个工具都能识别的项目 Skill，可以用 .agents/skills/ 这个跨客户端约定。

.agents/
└── skills/
    └── release-notes/
        └── SKILL.md

2. 编写 SKILL.md

先写一个窄描述和简短流程。只有真实测试证明需要更多内容时，再继续加。

---
name: release-notes
description: 根据合并的 PR、提交记录或 changelog 撰写面向客户的发布说明。
---

# 发布说明

当用户要你写发布说明、变更日志文案，或者面向客户的变更总结时，用这个 Skill。
不要把它用于内部迭代计划或只给工程师看的事故报告。

## 工作流
1. 找出用户可见的变更。
2. 按功能、修复、文档和内部项分组。
3. 写简洁的客户语言要点。
4. 除非用户明确要求，否则不要写纯内部变更。
5. 把不确定项列成问题。

## 输出格式
### Highlights
- ...

### Fixes
- ...

### Docs
- ...

### Open questions
- ...

3. 添加参考文件

参考文件可以让主 Skill 保持简短。这个例子加了一个语气指南，只在用户要客户文案时才加载。

.agents/
└── skills/
    └── release-notes/
        ├── SKILL.md
        └── references/
            └── customer-tone.md

# references/customer-tone.md

使用清晰的产品语言。
避免内部项目名、工单号和实现细节。
使用主动语态。
描述用户可见改进时，尽量用“你现在可以……”。
每个要点尽量控制在 25 个词以内。

4. 测试激活

发一个明显应该匹配描述的请求，然后确认 Agent 是否加载了这个 Skill，并按流程执行。

测试提示词 根据这些变更写客户发布说明："加入 SSO 登录"、"修复发票导出时区 bug"、"重构 billing worker"、"更新 API key 帮助文档"。把不清楚的地方标出来。

5. 期望输出

好的结果会遵守 Skill 的分组规则，并且不会把内部变更包装成产品更新。

### Highlights
- 现在可以使用 SSO 登录。

### Fixes
- 发票导出现在使用正确时区。

### Docs
- API key 设置文档已更新。

### Open questions
- billing worker 的重构是否应该作为内部内容排除？

6. 根据表现持续改进

如果 Skill 没激活，就把描述改得更像真实任务语言。
如果输出太虚，就补一个具体模板。
如果模型猜太多，就补默认值和“列出问题”的规则。
如果文件太大，就把参考资料拆成独立文件并按需加载。