Skill 编写指南

Skill 解决的是“同一类工作每次都要重新解释、重新纠错、重新找资料”的问题。它不是普通提示词收藏夹，而是给 Agent 的可复用操作手册：包含触发边界、执行顺序、必要资源、验证标准和安全停止条件。

最小 Skill 只有一个文件夹和一个 SKILL.md。frontmatter 里的 name 是身份，description 是触发入口；正文是匹配后才读取的执行说明。新手先把这一个文件写对，不要一开始就堆满脚本和长文档。

---
name: commit-message-helper
description: 根据当前仓库暂存区差异生成 3 个 Conventional Commit 候选。
  当用户要求为已暂存改动编写、润色或选择提交信息时使用。
  不用于普通 Git 问答，也不解释提交规范。
---

1. 先运行 `git diff --staged --stat` 和 `git diff --staged`。
2. 如果没有暂存区差异，停止并说明当前没有可用差异。
3. 只根据暂存区差异判断 type、subject 和可选 scope。
4. 严格输出 3 个候选，格式为 `type(optional-scope): subject`。
5. subject 不超过 72 个字符，结尾不要句号。
6. 只有路径或差异明显支持时才添加 scope。
7. 不运行 `git add`、`git commit`、`git push`，也不修改文件。

触发测试：
- 应触发：“给暂存区改动写 3 个提交信息”。
- 不应触发：“Conventional Commit 有哪些类型？”
- 应停止：`git diff --staged` 为空。

• name 用小写连字符，短且可识别。
• description 同时说明“做什么”和“什么时候用”，并排除近邻误触发。
• 正文只写触发后需要知道的动作、证据、停止条件和输出格式。

不要默认从空白文件开始。官方示例、一手仓库和维护良好的社区案例能提供结构参考；但安装前必须完整审计，不能只看 star 或截图。

好的 Skill 会把“每次都要看”和“特定分支才要看”的内容分层。SKILL.md 保持连续可读；长资料、脚本和模板按职责放到独立目录，避免污染上下文。

可以用 skill-creator 这类工具起草目录和 SKILL.md，但草稿不等于可用。你负责真实任务、触发边界、反例、验收标准和风险边界；AI 负责把材料整理成可审查的文件结构。

1. 先让 Agent 在真实文件、真实环境、真实目标下完整跑通一次。
2. 记录输入假设、工具顺序、失败恢复、验证命令和最终输出。
3. 先提炼可审核的工作流框架，不急着写完整 Skill。
4. 人工补齐边界、风险、反例和验收标准。
5. 再生成最终 SKILL.md，并用真实提示词做回归测试。

路由是让 Agent 选择分支。分支不是坏事，坏的是弱判断和延迟反馈。能用执行产生证据时，先执行低风险检查，再让证据决定下一步。

一次失败只是线索，不是新规则。先比较多个真实样例，确认失败有共性，再把共性写进 description、SKILL.md、scripts 或 references。

推荐从提交信息助手开始练习，因为它小、高频、输入证据明确，也容易看出错误边界。目标不是生成漂亮文案，而是练习触发范围、证据来源、副作用边界、输出格式和停止条件。

新手 Skill 最常见的问题不是语法，而是边界太松、证据太少、正文太散。下面这些检查点可以在提交前逐项对照。