write-a-skill

# 写作技能（Writing Skills）

## 流程（Process）

1. **收集需求** - 询问用户关于：
   - 该技能覆盖的任务/领域是什么？
   - 需要处理哪些具体使用场景？
   - 是否需要可执行脚本，还是只提供说明即可？
   - 是否需要附带参考资料？

2. **起草技能** - 创建：
   - 简洁的 `SKILL.md` 主说明
   - 若内容超过 500 行，补充额外参考文件
   - 若需要确定性操作，再添加工具脚本

3. **与用户一起复核** - 展示草稿并询问：
   - 这是否覆盖你的使用场景？
   - 是否有遗漏或不清楚之处？
   - 哪些章节需要更详细/更精简？

## 技能结构（Skill Structure）

```
skill-name/
├── SKILL.md           # 主说明（必需）
├── REFERENCE.md       # 详细文档（如需）
├── EXAMPLES.md        # 使用示例（如需）
└── scripts/           # 工具脚本（如需）
    └── helper.js
```

## SKILL.md 模板

```md
---
name: skill-name
description: 对能力的简短说明。适用于 [特定触发条件]。
---

# 技能名称

## 快速开始

[最小可用示例]

## 工作流

[包含检查清单的分步骤流程（适用于复杂任务）]

## 高级特性

[如需更详细内容：见 [REFERENCE.md](REFERENCE.md)]
```

## 描述要求（Description Requirements）

描述是你的 agent 在决定加载哪个技能时，**唯一会看到的内容**。它会与其他已安装技能一起展示在系统提示词中。agent 会读取这些描述，并根据用户请求选择最相关的技能。

**目标**：让 agent 只需要获得足够信息即可判断：

1. 该技能提供什么能力
2. 何时/为何触发它（具体关键词、上下文、文件类型等）

**格式要求**：

- 最多 1024 个字符
- 使用第三人称表述
- 第一句：做什么
- 第二句：使用“适用于 [特定触发条件]”

**良好示例**：

```
从 PDF 文件中提取文本与表格，填写表单并合并文档。适用于处理 PDF 文件，或用户提到 PDF、表单、文档提取等场景。
```

**不良示例**：

```
处理文档。
```

该不良示例无法让 agent 与其他文档类技能区分开来。

## 何时添加脚本（When to Add Scripts）

当需要以下情况时，添加工具脚本：
- 操作是确定性的（如校验、格式化）
- 同一段逻辑会被反复生成
- 错误需要显式处理

相较于生成代码，脚本可以节省 token，并提升稳定性与可预期性。

## 何时拆分文件（When to Split Files）

当出现以下情况时，将内容拆分到独立文件：
- `SKILL.md` 超过 100 行
- 内容属于不同领域（例如财务 vs 销售 schema）
- 高级特性很少需要

## 复核清单（Review Checklist）

起草完成后，请复核：

- [ ] 描述包含触发条件（例如“适用于...”）
- [ ] `SKILL.md` 行数少于 100
- [ ] 不包含时间敏感信息
- [ ] 术语前后一致
- [ ] 包含具体示例
- [ ] 引用内容只需一层（不要过度嵌套引用）