# 6.6 调试与优化 Skills

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

## 6.6.1 常见故障排除

以下是 Skills 开发和部署中最常见的几类故障，以及对应的排查方法。

### Skill 未被识别

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

**排查清单**：

* **文件名检查**：确保主文件名为 `SKILL.md`（全大写）。
* **路径检查**：确保 Skill 文件夹位于 Claude 配置的正确路径下。
  * Claude.ai：Settings → Features → Skills
  * Claude Code：`~/.claude/skills/` 或项目内 `.claude/skills/`
* **Frontmatter 格式**：检查 YAML 头部的缩进和冒号是否规范。

  ```yaml
  ---
  name: my-skill  # 这里的 name 必须唯一且简洁
  description: 简明扼要的描述
  ---
  ```
* **Description 质量**：如果格式正确但仍未触发，问题很可能出在 `description` 上。Description 是否足够具体？是否包含了触发关键词和使用场景？请参考 [6.4.6 Description 对比](/claude_guide/di-san-bu-fen-jin-jie-pian/06_skills/6.4_custom.md) 中的强弱对比示例。

### 参数传递错误

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

**解决方案**：

* 在 `SKILL.md` 中显式定义参数 Schema（如果有支持的格式）。
* 在 Prompt 部分增加示例（Few-shot），明确告诉 Claude 如何提取参数。

  > *示例：当用户说“查询北京天气”时，提取 `location="Beijing"` 作为参数。*
* 检查脚本是否正确处理了参数的默认值和边界情况。

### Skill 触发了错误的功能

**现象**：用户请求 A 功能，但 Claude 调用了 B Skill。

**解决方案**：

* **检查 Description 重叠**：两个 Skill 的 `description` 可能存在语义重叠。在 description 中添加 **边界说明**（“Not for...”），明确告诉 Claude 何时*不应该*使用这个 Skill。
* **使用差异化关键词**：确保每个 Skill 的 description 中包含独特的动词和名词，避免模糊表述。

### 脚本执行失败

**现象**：Skill 被正确识别并调用，但 Python/Bash 脚本运行报错。

**排查步骤**：

1. **本地独立测试**：先在本地终端独立运行脚本，确认脚本本身无误。

   ```bash
   python scripts/process.py --input "test data"
   ```
2. **检查依赖**：确认运行环境中安装了脚本所需的所有依赖库。
3. **检查路径**：脚本中的文件引用应使用相对路径（相对于 Skill 根目录），或在 `SKILL.md` 中明确指定工作目录。
4. **查看错误输出**：确保脚本在失败时打印了有意义的错误信息到 `stderr`，而不是只返回一个退出码。

## 6.6.2 性能优化技巧

### 减少上下文消耗

不要把整个项目的文档都塞进 Skill。上下文窗口是稀缺资源，应精打细算。

* **Bad**：“这里是整个 API 文档 (50k tokens)...”
* **Good**：只放入这一个 Skill 真正需要的 API 端点说明。
* **Best**：采用渐进式披露模式（参见 [6.2.6](/claude_guide/di-san-bu-fen-jin-jie-pian/06_skills/6.2_structure.md)），将详细文档拆分到子文件中，由 Claude 按需读取。

### 脚本优先于 Prompt

对于确定性任务（精确格式化、数学计算、文件转换），使用脚本比依赖 Prompt 更快、更准确、更省 Token。

| 方式        | 速度      | 准确性        | Token 消耗 |
| --------- | ------- | ---------- | -------- |
| Prompt 指令 | 慢（需要推理） | 中等（可能偶尔出错） | 高        |
| Python 脚本 | 快（直接执行） | 100%（代码保证） | 低（仅调用开销） |

### “Turbo” 模式

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

## 6.6.3 调试工具与方法

### 使用 Skill Creator 自检

Anthropic 提供的 `skill-creator` Skill 不仅能帮助创建新 Skill，还可以对现有 Skill 进行结构验证。将你的 `SKILL.md` 提供给 Skill Creator，让它检查格式是否规范、description 是否清晰。

### 对比测试法

当怀疑 Skill 效果不佳时，进行 A/B 对比：

1. **禁用 Skill**：暂时移除 Skill，用纯 Prompt 方式完成同一任务。
2. **启用 Skill**：使用 Skill 完成同一任务。
3. **对比结果**：从准确性、速度和 Token 消耗三个维度评估差异。

### 日志追踪

在脚本中添加详细的日志输出，帮助定位问题：

```python
import hashlib
import sys

def process(data):
    data_hash = hashlib.sha256(data.encode("utf-8")).hexdigest()
    print(f"[DEBUG] 收到输入数据: {len(data)} 字符，sha256={data_hash}", file=sys.stderr)
    try:
        result = do_something(data)
        print(f"[DEBUG] 处理成功，输出 {len(result)} 字节", file=sys.stderr)
        return result
    except Exception as e:
        print(f"[ERROR] 处理失败: {type(e).__name__}", file=sys.stderr)
        raise
```

## 6.6.4 最佳实践清单

1. **单一职责原则**：一个 Skill 只干一件事。不要试图做一个“万能 Skill”。
2. **原子化脚本**：底层的 Python/Bash 脚本应尽可能独立，方便本地测试。
3. **清晰的错误提示**：当脚本执行失败时，不要只返回 `Exit Code 1`，而要打印具体的错误原因（如“API Key 无效”），这样 Claude 才能看懂并尝试自我修复。
4. **版本标注**：在 `SKILL.md` 的 frontmatter 或正文中标注版本号，便于团队协作时追踪变更。
5. **定期迭代**：根据实际使用中的反馈（如“为什么这个 Skill 没被触发？”或“为什么执行结果不对？”），持续微调 `description` 和 `instructions`。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/claude_guide/di-san-bu-fen-jin-jie-pian/06_skills/6.6_debugging.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.