skill-doc-authoring

技能文档编写

编写一个有效的 SKILL.md，让 Agent 确实会触发并遵循它。这样可以避免两种失败情况：技能从不触发（描述不够明确），以及技能触发了却没有帮助（正文含糊）。

文件约定

• 目录名称必须与 name: 匹配，且只能使用小写字母和连字符，长度 ≤ 64 个字符。
• 文件名必须严格为 SKILL.md（区分大小写）。
• Frontmatter 必须且只能包含两个键：name、description。description 长度 ≤ 1024 个字符。

skills/<skill-name>/SKILL.md

描述就是触发条件

Agent 仅根据 description 决定是否加载技能。用第三人称撰写，开头说明技能的作用，然后写 “Use when …”，并列出具体的用户说法和使用场景。包含用户实际会输入的触发词。

• 较弱：处理数据的工作流。
• 较强：在导入前验证并清理 CSV 导出文件。Use when 用户上传 CSV、提到“脏数据”，或要求“为数据库做好准备”。

如果有相近的同级技能，请说明何时不要使用此技能；触发条件重叠会导致错误的技能被触发。

正文结构

为不了解项目背景的 Agent 撰写。内容简洁、使用祈使句，并以决策为导向。

# Title
One-line purpose.
## When to use            # + when not to
## Procedure / The loop   # numbered, concrete, with commands
## Quality bar            # how to know it's done right
## Anti-patterns          # the tempting wrong moves

规则：

• 使用祈使语气（“运行 X”“验证 Y”），而不是“Agent 应考虑……”。
• 每个步骤都必须可验证，或包含具体命令／示例。
• 删除“说明”“概述”等填充内容和重复表述。如果某行不会改变 Agent 的操作，就删掉。
• 将较长的参考资料（架构、表格、脚本）放在同级文件中并链接过去；让 SKILL.md 易于浏览（目标：少于约 200 行）。

流程

1. 从用户提供的信息中提取实际流程（SOP、他们实际执行的步骤、决策及其标准）。
2. 确定触发条件：需要此技能前，用户会说什么或做什么？
3. 起草描述（触发测试：这些说法会触发技能吗？无关说法不会触发吗？）。
4. 按上述结构编写正文。
5. 验证：文件名、名称／目录是否匹配、Frontmatter 键、描述长度。
6. 在脑海中进行试运行：将此技能交给一个没有上下文的 Agent，测试 2–3 个示例请求——它是否确切知道该做什么？

反模式

• 通用骨架（概述 → “此技能可实现……” → 名词列表 → 说明），适用于任何主题，却对任何主题都没有帮助。
• 描述只介绍领域，从不说明何时触发。
• 重述模型已经了解的一般最佳实践，而不是用户的具体流程。
• 把所有内容塞进一个 SKILL.md，而实际上一个脚本加一份简短文档会更合适。