> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/claude_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/claude_guide/di-san-bu-fen-jin-jie-pian/06_skills/6.6_debugging.md).

# 6.6 调试与优化 Skills

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

## 6.6.1 常见故障排除

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

### Skill 未被识别

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

**排查清单**：

* **文件名检查**：确保主文件名为 `SKILL.md`（全大写）。
* **路径检查**：确保 Skill 文件夹位于 Claude 配置的正确路径下。
  * Claude.ai：Customize → Skills（需先在 Settings → Capabilities 启用代码执行）
  * 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`, `Grep`），可以配置自动运行，无需用户逐次确认。在 Claude Code 中，官方做法是在 `SKILL.md` 的 frontmatter 中声明 `allowed-tools: Read Grep`（字段详解参见 [6.4.1](/claude_guide/di-san-bu-fen-jin-jie-pian/06_skills/6.4_custom.md)），或在 `settings.json` 的 permissions 规则中放行只读工具。`// turbo` 这类步骤级标注是 Windsurf 等其他工具链的工作流语法，对 Claude 的 `SKILL.md` 不生效，不要混用。

## 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`。