AI 原生开放教材

外观

Claude Code & OpenClaw & Codex & WorkBuddy 中文教程课时教程·中文原文 ↗原件 ↓仓库 ↗

第七部分：故障排查 ​

本部分的：快速解决Skill配置和运行中的常见问题。

7.1 常见错误及解决方案 ​

错误1：Skill未激活 ​

症状：输入触发词没有反应

可能原因：

  1. SKILL.md 文件格式错误
  2. description 配置不当
  3. 文件路径不正确

解决方案：

bash
# 1. 检查SKILL.md格式
head -n 5 .claude/skills/你的skill/SKILL.md

# 应该显示：
# ---
# name: skill-name
# description: 触发描述
# ---

# 2. 验证YAML Frontmatter格式（在线工具）
# 访问 https://www.yamllint.com/ 粘贴YAML部分检查

# 3. 检查description是否清晰
# description应该明确说明何时激活，例如：
# ✅ "当用户要求'添加注释'或'代码注释'时激活"
# ❌ "代码注释工具"（太模糊）

# 4. 验证文件路径
ls -la .claude/skills/你的skill/
# 应该看到 SKILL.md 文件

# 5. 测试触发词
# 在Claude Code中输入description中的关键词

错误2：提示词未生效 ​

症状：AI回复不符合Skill风格

可能原因：

  1. Markdown Body格式错误
  2. 指令不够明确
  3. Hot Reloading未生效

解决方案：

bash
# 1. 检查SKILL.md完整格式
cat .claude/skills/你的skill/SKILL.md

# 应该包含：
# --- (YAML开始)
# name: xxx
# description: xxx
# --- (YAML结束)
#
# # 标题 (Markdown开始)
# ## 章节
# 内容...

# 2. 验证Markdown Body结构
# 确保使用了清晰的标题结构：
# ## 一、角色定义
# ## 二、工作流程
# ## 三、规则约束

# 3. 测试Hot Reloading
# 修改SKILL.md后，发送新消息测试
# 如果未生效，尝试开始新对话或使用 /compact 压缩上下文

# 4. 检查指令明确性
# 在SKILL.md中使用明确的指令：
# ✅ "你必须使用简洁的中文，避免AI腔"
# ❌ "建议使用自然语言"（太弱）

错误3：脚本执行失败 ​

症状：调用脚本时报错

可能原因：

  1. Python路径问题
  2. 脚本权限问题
  3. 依赖包未安装

解决方案：

bash
# 1. 检查Python是否可用
python --version
# 或
python3 --version

# 2. 检查脚本权限（macOS/Linux）
chmod +x .claude/skills/你的skill/scripts/*.py

# 3. 安装依赖
pip install -r .claude/skills/你的skill/requirements.txt

# 4. 手动测试脚本
cd .claude/skills/你的skill/scripts
python 脚本名.py "测试输入"

错误4：YAML解析错误 ​

症状：加载时报语法错误

可能原因：

  1. YAML Frontmatter格式错误
  2. ---分隔符缺失或多余
  3. 特殊字符未转义

解决方案：

yaml
# ❌ 错误：缺少结束的---
---
name: my-skill
description: 测试

# ❌ 错误：冒号后没有空格
name:"我的Skill"

# ✅ 正确：完整的YAML Frontmatter
---
name: my-skill
description: 当用户需要时激活
---

# 这里开始是Markdown Body

# Skill标题
内容...

验证YAML格式：

bash
# 方法1：使用在线工具
# 访问 https://www.yamllint.com/
# 复制YAML Frontmatter部分（不包括---分隔符）进行验证

# 方法2：使用Python验证
python3 -c "
import yaml
import sys

with open('.claude/skills/你的skill/SKILL.md', 'r', encoding='utf-8') as f:
    content = f.read()

# 提取YAML部分
yaml_start = content.find('---')
yaml_end = content.find('---', yaml_start + 3)
yaml_content = content[yaml_start+3:yaml_end].strip()

try:
    yaml.safe_load(yaml_content)
    print('✅ YAML格式正确')
except yaml.YAMLError as e:
    print(f'❌ YAML错误: {e}')
    sys.exit(1)
"

7.2 调试技巧 ​

技巧1：验证SKILL.md结构

bash
# 检查SKILL.md基本结构
cat .claude/skills/你的skill/SKILL.md | head -n 20

# 应该看到：
# ---
# name: xxx
# description: xxx
# ---
# (空行)
# # Markdown标题
# 内容...

技巧2：测试Hot Reloading

bash
# 1. 修改SKILL.md
# 添加或修改一些指令

# 2. 在Claude Code中发送新消息
# 不需要重启，修改会自动生效

# 3. 验证修改是否生效
# 检查AI是否应用了新的指令

# 如果未生效，尝试开始新对话或：
/compact

技巧3：手动测试脚本

bash
# 直接运行脚本看输出
cd .claude/skills/你的skill/scripts
python 脚本名.py "测试输入" --json

# 检查返回码
echo $?  # 0表示成功，非0表示失败

技巧4：检查文件编码

bash
# 确保文件是UTF-8编码
file .claude/skills/你的skill/SKILL.md
# 应显示：UTF-8 Unicode text

技巧5：查看Skill加载日志

在Claude Code中输入：

请列出当前已加载的所有Skills

这会显示所有被识别的Skills及其基本信息。

7.3 v2.1.129+ 新增：skillOverrides 设置 ​

当你的项目或团队安装了大量 Skills 时，有些可能暂时不想用。从 v2.1.129 起，Claude Code 支持 skillOverrides 设置来控制每个 Skill 的可见性。

三种覆盖状态 ​

值效果
off完全隐藏该 Skill（等同于不存在）
user-invocable-only只保留 / 手动调用，禁止 Claude 自动激活
name-only只在 /skills 列表中显示名称，不加载任何指令

配置位置 ​

skillOverrides 写在 settings 文件中（项目级 .claude/settings.json 或用户级 ~/.claude/settings.json）：

json
{
  "skillOverrides": {
    "gongzhonghao-writer": "user-invocable-only",
    "legacy-helper": "off",
    "experimental-tool": "name-only"
  }
}

适用场景：

  • 团队有几十个 Skills，但某个项目只想用其中几个 → 把其余设为 off
  • 某个 Skill 自动激活太频繁，但不舍得删 → 改为 user-invocable-only
  • 排查 Skill 冲突时，临时关闭部分 Skill

7.4 /skills 搜索过滤 ​

当你安装了大量 Skills 时，直接输入 /skills 列表会很长。在较新版本中，/skills 支持搜索过滤：

text
/skills <关键词>

例如 /skills comment 会过滤出名称或描述中包含 "comment" 的 Skill。这在管理十几个以上 Skill 时非常有用。