提示工程与技能调试指南：打造高可用 Skill

开发 Agent Skill 就像教一个聪明的实习生做事。有时候他一听就懂，有时候却死活不按你的要求来。

本章将聚焦于 调试（Debugging） 和 优化（Optimization）。我们将深入探讨为什么 AI 会“无视”你的 Skill，以及如何通过提示工程（Prompt Engineering）让 Skill 变得百发百中。

1. 常见故障：为什么 AI 不调用我的 Skill？

Q: 我写了 SKILL.md，也注册了，但不管我怎么问，AI 就是不调用它，而是自己瞎编代码。

A: 这是最常见的“路由失败”（Routing Failure）。通常有三个原因：

描述过于笼统 (Vague Description)
- Bad: "一个很有用的工具。"
- AI 心理: "不知道干嘛的，保险起见还是用我自己的知识吧。"
- Fix: 明确 What (功能), When (触发时机), **Input (输入)**。
重叠冲突 (Overlapping Skills)
- 如果你有一个 python-helper 和一个 code-runner，且描述相似，AI 会困惑。
- Fix: 明确界定边界。例如 python-helper 仅用于语法检查，code-runner 仅用于执行。
示例误导 (Misleading Examples)
- Examples 里的问答如果不自然，或者与 Description 矛盾，会降低 AI 的置信度。

Q: 有什么万能公式可以写出完美的 Description 吗？

A: 有一个被验证有效的模板：角色 + 任务 + 约束。

## Description
[角色] 这是一个专门用于重构 React 组件的专家工具。
[任务] 当用户要求“拆分组件”、“提取 Hook”或优化渲染性能时使用。
[约束] 仅适用于 .jsx/.tsx 文件。不要在 Vue 项目中使用。

技巧：Negative Prompting (反向提示)
告诉 AI 不要做什么往往更有效。

"不要在用户仅仅询问代码解释时调用此工具，仅在用户明确要求修改代码时调用。"

Q: Examples 部分到底要写多少个？

A: 质量 > 数量。通常 3-5 个 具有代表性的示例最佳。

黄金法则：覆盖边界情况 (Edge Cases)

示例 1：标准调用
- User: "格式化 main.py" -> Call: format main.py
示例 2：带参数的复杂调用
- User: "把 src 目录下所有文件都格式化一下" -> Call: format src/
示例 3：含糊指令的澄清
- User: "代码有点乱" -> Assistant: "你想让我帮你格式化代码吗？如果是的话..." (展示 AI 如何引导用户触发 Skill)

Q: 我的 Skill 运行很慢，或者感觉很费 Token，怎么办？

减少 Output 输出：
- AI 需要阅读脚本的每一个字符输出。如果脚本打印了 10MB 的日志，AI 会变慢甚至 Token 溢出。
- 优化: 在脚本中截断输出，只打印关键信息（如最后 50 行日志）。
**精简 SKILL.md**：
- SKILL.md 的内容是作为 System Prompt 发送给 AI 的。
- 删除废话，保持简洁。注释掉的旧代码和无关的文档都要删掉。
本地缓存：
- 如果脚本需要联网下载数据，尽量做本地缓存，避免每次调用都等待网络。

Q: 有没有类似 console.log 的东西来调试 Skill？

**显式询问 (Ask the AI)**：
- 在对话中直接问："你为什么决定调用（或不调用）这个 Skill？"
- Claude Code 通常会解释它的思考路径（"因为你的描述说只支持 Python，但用户给的是 JS 文件"）。
Verbose 模式：
- 大多数 CLI 工具都有 -v 或 --verbose 选项，可以看到 AI 接收到的完整 Prompt 和原始 API 响应。
隔离测试：
- 在一个干净的对话 Session 中单独测试 Skill，排除上下文干扰。

编写 Agent Skill 本质上是在对 AI 进行编程。代码的语法是自然语言，编译器是 LLM。

掌握了这些调试技巧，你就能写出稳定、高效且“懂事”的技能。

在下一章（也是最后一章），我们将走出本地环境，看看如何将你的杰作打包分享，发布到开源社区和 Skills Marketplace。

参考资源：