Skill 编写技巧

Skill 不是「提示词模板」，而是一段驱动 AI Agent 完成真实任务的工作流程指令。AI 读取你的 SKILL.md，然后调用工具（读写文件、执行脚本、操作浏览器……）把事情做完。写好 Skill 的关键，是把你的「专家判断」翻译成 AI 可以执行的步骤。

1. description 是最重要的字段

description 决定 AI 在什么时候调用你的 Skill。写得不好，Skill 就不会被触发——再好的正文也没用。

写法原则：
- 先说 Skill 能做什么
- 再列出触发关键词和场景，越具体越好
- 宁可多触发，不要漏触发

# ❌ 太模糊
description: 'Helps with code review'

# ✅ 具体，触发准确
description: 'Reviews code for bugs, style issues, and performance problems.
  Use whenever the user pastes code and asks for feedback, says "review this",
  "check my code", "what's wrong here", or wants a PR review — even if they
  just say "look at this function".'

用单引号包裹 description，避免冒号等字符导致 YAML 解析失败。

2. 正文写的是「工作流程」，不是「角色设定」

Skill 正文不是 system prompt，不要写「你是一个拥有 10 年经验的……」这种角色描述。

正文应该写：做什么、按什么顺序、用什么工具、输出什么。

# Code Reviewer

## 执行步骤

1. 读取用户提供的代码或文件路径
2. 逐项检查：
   - 有无明显 bug 或边界条件遗漏
   - 命名是否清晰，逻辑是否可读
   - 有无性能隐患（N+1、不必要的循环等）
3. 按严重程度分级输出：🔴 必须修改 / 🟡 建议优化 / 🟢 可选改进
4. 每条问题附上修改建议和示例代码

用祈使句写指令（"读取"、"检查"、"输出"），AI 执行效果更稳定。

3. 让 Skill 真正「做事」，而不是「回答」

好的 Skill 驱动 AI 使用工具完成任务，而不只是生成一段文字回复。

  • 读写文件：分析代码库、生成报告、修改配置
  • 执行脚本：数据处理、API 调用、批量操作
  • 操作浏览器：抓取页面、自动填表、截图存档
## 执行步骤

1. 用 glob 工具找到项目里所有 `*.rb` 文件
2. 用 file_reader 读取每个文件，检查是否有 `TODO` 注释
3. 汇总结果，写入 `todo_report.md`
4. 告知用户报告已生成，路径为 `./todo_report.md`

如果你的 Skill 只是「生成一段文字」，它的价值有限。让它做完整的任务，价值才会真正体现。

4. 把专业判断写进去，而不是靠 AI 猜

Skill 最大的价值是把你的行业经验和判断标准编码进去。不要让 AI 自由发挥，要告诉它你的标准。

# ❌ 模糊，AI 会用通用标准
检查代码质量

# ✅ 明确，AI 按你的标准执行
检查以下几点（按我们团队规范）：
- 所有公开方法必须有注释
- 禁止使用 rescue Exception，只允许 rescue StandardError
- 数据库查询必须加 limit，防止全表扫描
- 变量名长度不得少于 3 个字符（除循环变量 i/j/k）

5. 大内容放 references/，保持正文精简

SKILL.md 正文建议控制在 500 行以内。大块参考内容（行业规范、数据字典、模板库）放到 references/ 目录，在正文中写明何时读取：

## 检查标准

详细规范见 `references/code-style-guide.md`，在开始检查前先读取该文件。

scripts/ 目录放可复用脚本（推荐 Ruby），避免在正文中写内联 shell 命令：

## 数据处理

运行 `ruby SKILL_DIR/scripts/parse_report.rb <input_file>` 处理输入数据。

6. 从一个真实场景开始，再泛化

不要一开始就写「万能」的 Skill。先针对一个具体场景写好，测试通过后再泛化：

  1. 选一个你最熟悉的典型场景，把它做好
  2. 用 /skill-creator 测试：用 3–5 个真实输入跑一遍，看输出是否符合预期
  3. 发现偏差就修正：在 SKILL.md 里补充说明，而不是靠用户自己摸索
  4. 满意后再扩展：增加边界情况处理、更多场景支持

7. 用 /skill-creator 迭代，而不是凭感觉改

/skill-creator 内置了评估（eval）流程：写测试用例 → 跑对比（有 Skill vs 无 Skill）→ 查看结果 → 修改 → 重复。

这是改进 Skill 最可靠的方式，比凭感觉调整 prompt 效率高得多。

Skill 基础概念
白标打包