Skills 调试

Skill 写好后，常常会遇到"没有触发"、"执行出错"、"输出不对"等问题。

本篇介绍排查这些问题的基本思路和方法。

调试的三类常见问题

问题类型	现象	优先排查点
未触发	Claude 完全没有使用 Skill	description 写法、任务复杂度
触发但执行错误	Skill 被读取，但脚本运行失败	脚本路径、依赖、参数格式
触发且执行，但结果不符合预期	输出内容与期望有出入	SKILL.md 指令清晰度

调试问题一：Skill 未触发

这是最常见的问题，排查步骤如下：

第一步：确认 Skill 文件被正确加载

实例

# 检查 Skill 目录结构是否正确
ls -la my-skill/

# 确认 SKILL.md 存在且非空
wc -l my-skill/SKILL.md

-rw-r--r-- 1 user user  842 May 18 10:00 SKILL.md

第二步：检查 YAML frontmatter 格式

frontmatter 格式错误会导致 Skill 无法被识别。

---
name: my-skill
description: 这是一个示例 Skill，处理用户上传的文本文件。
---

# My Skill
...

frontmatter 必须以 --- 开始和结束，name 和 description 字段名不能有多余空格，冒号后必须有一个空格。

第三步：使用更复杂的测试提示词

简单任务（如"读取这个文件"）可能不会触发 Skill。

将测试提示词改为多步骤、有明确输出格式要求的复杂请求。

不易触发的提示词	更易触发的提示词
"分析这个文件"	"分析这份销售数据 CSV，找出月度增长趋势，生成统计摘要表格"
"生成一个 PPT"	"根据这份报告，创建一个 10 页的产品介绍演示文稿，要有图表和摘要"

调试问题二：脚本执行错误

脚本出错时，错误信息会出现在命令行输出中。

在 Claude 会话里，可以直接让 Claude 运行脚本并查看输出：

实例

# 手动运行脚本，检查错误输出
python scripts/process.py /mnt/user-data/uploads/test.csv

# 加 -v（verbose）参数查看详细日志（如果脚本支持）
python scripts/process.py /mnt/user-data/uploads/test.csv --verbose

常见错误类型与修复方法

错误信息	原因	修复方法
`ModuleNotFoundError: No module named 'pandas'`	依赖未安装	运行 `pip install pandas --break-system-packages`
`FileNotFoundError: [Errno 2]`	文件路径错误	检查文件是否在 `/mnt/user-data/uploads/`
`PermissionError: [Errno 13]`	无写入权限	将输出目标改为 `/mnt/user-data/outputs/`
`SyntaxError`	脚本语法错误	用 `python -m py_compile 脚本名.py` 检查

快速语法检查

实例

# 检查 Python 脚本语法（不执行，只验证语法）
python -m py_compile scripts/process.py && echo "语法正确" || echo "语法错误"

# 检查 Shell 脚本语法
bash -n scripts/run.sh && echo "语法正确" || echo "语法错误"

语法正确

调试问题三：输出结果不符合预期

这类问题通常源于 SKILL.md 中的指令不够清晰，或者存在歧义。

排查方法：逐步缩小范围

在 SKILL.md 中临时添加调试输出指令，观察 Claude 每一步的理解：

## 调试模式（开发时使用，发布前删除）

执行前，先输出以下信息供确认：
1. 识别到的输入文件路径
2. 用户期望的输出格式
3. 计划执行的步骤列表

等待用户确认后再继续执行。

常见的指令歧义问题

含糊写法	清晰写法
"处理完成后输出结果"	"将结果保存到 /mnt/user-data/outputs/ 目录，并在对话中展示文件路径"
"分析数据"	"计算各列的均值、中位数、标准差，并以 Markdown 表格形式输出"
"生成报告"	"生成一个包含摘要段落、数据表格和结论的 HTML 文件，保存到输出目录"

使用 print 进行脚本内调试

在脚本关键节点添加打印语句，是排查执行流程问题最直接的方式。

实例

# 文件路径：scripts/debug_example.py
import sys

def process_file(file_path: str):
print(f"[DEBUG] 开始处理文件：{file_path}") # 调试点 1

with open(file_path, "r", encoding="utf-8") as f:
content = f.read()

print(f"[DEBUG] 文件读取成功，大小：{len(content)} 字节") # 调试点 2

lines = content.split("\n")
print(f"[DEBUG] 总行数：{len(lines)}") # 调试点 3

# 实际处理逻辑
result = [line.strip() for line in lines if line.strip()]
print(f"[DEBUG] 处理后有效行数：{len(result)}") # 调试点 4

return result

if __name__ == "__main__":
output = process_file(sys.argv[1])
print("\n--- 处理结果 ---")
for line in output[:5]: # 只显示前 5 行
print(line)

[DEBUG] 开始处理文件：/mnt/user-data/uploads/sample.txt
[DEBUG] 文件读取成功，大小：1024 字节
[DEBUG] 总行数：32
[DEBUG] 处理后有效行数：28

--- 处理结果 ---
第一行内容
第二行内容
...

调试完成后，记得删除 [DEBUG] 开头的 print 语句，避免正式输出中混入调试信息。