6.6 调试与优化 Skills

创建 Skills 只是第一步，在实际生产环境中，你可能会遇到 Skills 不生效、参数传递错误或执行效率低下的问题。本节将介绍一套系统的调试与优化方法论。

6.6.1 常见故障排除

1. Skill 未被识别

现象：Claude 回复“我不知道如何执行这个任务”，或者完全忽略了你的 SKILL.md。 排查清单：

• 文件名检查：确保主文件名为 SKILL.md（全大写）。

• 路径检查：确保 Skill 文件夹位于 Claude 配置的正确路径下。

• Frontmatter 格式：检查 YAML 头部的缩进和冒号是否规范。

  ---
  name: my-skill  # 这里的 name 必须唯一且简洁
  description: 简明扼要的描述
  ---

2. 参数传递错误

现象：Skill 被调用了，但脚本报错“缺少参数”或参数值为空。 解决方案：

• 在 SKILL.md 中显式定义参数 Schema（如果有支持的格式）。

• 在 Prompt 部分增加示例（Few-shot），明确告诉 Claude 如何提取参数。

  示例：当用户说“查询北京天气”时，提取 location="Beijing" 作为参数。

6.6.2 性能优化技巧

1. 减少上下文消耗 (Context Diet)

不要把整个项目的文档都塞进 Skill。

• Bad: "这里是整个 API 文档 (50k tokens)..."

• Good: 只放入这一个 Skill 真正需要的 API 端点说明。

2. "Turbo" 模式 (Auto-run)

对于没有副作用的只读操作（如 read_file, grep_search），可以在工作流中配置自动运行，无需用户逐次确认。 在 SKILL.md 对应的步骤前添加标注（具体语法视工具链而定，例如 // turbo）。

6.6.3 最佳实践清单

1. 单一职责原则：一个 Skill 只干一件事。不要试图做一个“万能 Skill”。

2. 原子化脚本：底层的 Python/Bash 脚本应尽可能独立，方便本地测试。

3. 清晰的错误提示：当脚本执行失败时，不要只返回 Exit Code 1，而要打印具体的错误原因（如“API Key 无效”），这样 Claude 才能看懂并尝试自我修复。