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 - [ ] 不包含时间敏感信息 - [ ] 术语前后一致 - [ ] 包含具体示例 - [ ] 引用内容只需一层（不要过度嵌套引用）