跳到主要内容

调试技巧

本章汇总 Skill 开发和使用中的常见问题及解决方案，帮助你快速定位和解决问题。

Skill 不触发​

Skill 未被自动激活是最常见的问题之一。

检查 description​

description 是 Skill 触发的关键。确保它包含：

  1. 功能描述：清晰说明 Skill 做什么
  2. 触发条件：明确说明何时使用
  3. 关键词：包含用户可能使用的词汇
# 好的 description
description: "审查 Python 代码质量，检查 PEP 8 规范。当用户请求代码审查、代码检查、code review 或提交 Python 代码时触发。"

# 不好的 description（缺少触发条件）
description: "Python 代码审查工具"

检查关键词匹配​

用户输入是否包含 description 中的关键词？尝试使用描述中的词汇重新表达需求：

用户尝试：帮我看看这段代码
修改为：请审查这段代码

用户尝试：修一下这个
修改为：检查这个 Python 文件的问题

显式调用​

如果 Skill 未自动触发，可以使用显式调用方式：

/skill-name
# 或
$skill-name

检查目录位置​

确认 Skill 位于正确的目录：

# Claude Code
.claude/skills/my-skill/SKILL.md

# OpenAI Codex
.codex/skills/my-skill/SKILL.md

# 跨客户端共享
.agents/skills/my-skill/SKILL.md

检查 disable-model-invocation​

如果 Skill 设置了 disable-model-invocation: true，它不会自动触发：

---
name: "deploy"
description: "部署到生产环境"
disable-model-invocation: true  # 禁止自动触发
---

这种 Skill 只能通过显式调用（/deploy）使用。

Skill 触发过于频繁​

Skill 在不应该触发的时候被激活。

使 description 更具体​

# 太宽泛
description: "处理代码相关的问题"

# 更具体
description: "审查 Python 代码质量。仅当用户明确请求代码审查时触发，不适用于代码编写或调试场景。"

添加排除条件​

description: "审查 Python 代码质量。当用户请求代码审查时触发。注意：不适用于代码编写、调试或解释场景。"

使用 disable-model-invocation​

如果只想手动调用，禁用自动触发：

---
name: "deploy"
disable-model-invocation: true
---

输出不符合预期​

Skill 触发了但输出质量不佳。

检查指令清晰度​

指令是否足够具体？添加更多细节：

# 不够具体
## 输出格式
输出审查结果。

# 更具体
## 输出格式
### 审查摘要
- 文件：[文件名]
- 问题总数：[数量]

### 严重问题
| 行号 | 问题 | 建议 |
|------|------|------|

### 总体评价
评分：x/10

添加示例​

提供输出示例比抽象描述更有效：

## 输出示例

### 审查摘要
- 文件：user_service.py
- 问题总数：3

### 严重问题
| 行号 | 问题 | 建议 |
|------|------|------|
| 15 | 未处理 None | 添加检查 |

添加检查清单​

使用检查清单确保不遗漏：

## 检查清单

- [ ] 命名规范
- [ ] 类型注解
- [ ] 文档字符串
- [ ] 错误处理

验证失败​

使用 skills-ref validate 时报告错误。

常见错误及解决方案​

错误信息原因解决方案
Missing required field: name缺少 name 字段添加 name: "skill-name"
Missing required field: description缺少 description 字段添加 description
Invalid name formatname 包含非法字符只使用小写字母、数字、连字符
Name does not match directoryname 与目录名不一致修改 name 或重命名目录
Description exceeds 1024 charactersdescription 太长缩短到 1024 字符内
Description is emptydescription 为空添加有意义的描述
Invalid YAML syntaxYAML 格式错误检查缩进、引号、特殊字符

YAML 格式问题​

常见 YAML 格式错误：

# 错误：未引用包含冒号的值
description: 处理 API: 连接问题

# 正确：使用引号
description: "处理 API: 连接问题"

# 错误：缩进不一致
metadata:
  author: name
   version: 1.0  # 缩进多了一个空格

# 正确：保持一致缩进
metadata:
  author: name
  version: 1.0

Skill 看不到/未加载​

安装的 Skill 没有出现在可用列表中。

检查文件名​

确保文件名正确：

✅ 正确
my-skill/SKILL.md  # 大写 SKILL.md

❌ 错误
my-skill/skill.md  # 小写
my-skill/SKILLS.md # 多了 S

检查目录结构​

✅ 正确结构
.claude/skills/
└── my-skill/
    └── SKILL.md

❌ 错误结构
.claude/skills/
└── my-skill.md  # 直接是文件，没有目录

检查信任设置​

某些工具要求将项目标记为受信任才加载项目级 Skills：

# 在 VS Code 中
# 点击"信任此文件夹"或修改设置

检查 Skills 数量限制​

如果 Skills 太多，可能超出字符预算：

# Claude Code 查看上下文
/context

# 如果看到警告，考虑：
# 1. 减少不常用的 Skills
# 2. 设置环境变量调整限制
export SLASH_COMMAND_TOOL_CHAR_BUDGET=32000

资源文件加载问题​

引用的脚本或参考文件无法加载。

检查路径​

使用相对于 Skill 根目录的相对路径：

# 正确
执行 `scripts/analyze.py`
参考 `references/api-docs.md`

# 错误（绝对路径）
执行 `/Users/name/.claude/skills/my-skill/scripts/analyze.py`

检查文件存在​

# 确认文件存在
ls .claude/skills/my-skill/scripts/

检查权限​

脚本需要执行权限：

# 添加执行权限
chmod +x scripts/analyze.py

性能问题​

Skill 执行缓慢或消耗过多资源。

优化 SKILL.md 大小​

保持 SKILL.md 简洁：

  • 建议 < 500 行
  • 建议 < 5000 tokens
  • 详细内容移到 references/

使用渐进式披露​

# SKILL.md - 只包含核心指令
## 错误处理
如果遇到 API 错误，查阅 `references/error-codes.md`

# references/error-codes.md - 详细错误码表
# 只在需要时加载

减少重复加载​

避免在每次对话中都重新加载 Skill：

  • 某些工具支持去重激活
  • 检查是否已激活再加载

多工具兼容问题​

同一个 Skill 在不同工具中表现不一致。

使用标准格式​

遵循 Agent Skills 开放标准，避免使用特定工具的专有功能：

# 标准字段（跨工具兼容）
---
name: "skill-name"
description: "描述"
---

# 特定工具字段（可能不兼容）
---
name: "skill-name"
description: "描述"
argument-hint: "[file]"  # Claude Code 特有
allowed-tools: "read_file"  # 部分工具支持
---

测试多个工具​

在不同工具中测试 Skill：

# 复制到 Claude Code
cp -r my-skill .claude/skills/

# 复制到 OpenAI Codex
cp -r my-skill .codex/skills/

# 复制到跨客户端共享目录
cp -r my-skill .agents/skills/

检查目录位置​

不同工具使用不同的目录：

工具项目级目录
Claude Code.claude/skills/
OpenAI Codex.codex/skills/
跨客户端.agents/skills/

调试技巧​

查看加载的 Skills​

# Claude Code
# 在对话中询问
"列出所有可用的 skills"

# 或使用命令
/skills

检查 Skill 内容​

# 直接查看 SKILL.md 内容
cat .claude/skills/my-skill/SKILL.md

分步测试​

  1. 最小测试：创建只包含 name 和 description 的 Skill
  2. 逐步添加：一次添加一部分指令，测试效果
  3. 隔离问题：确定是触发问题还是执行问题

使用验证工具​

# 验证单个 Skill
npx skills-ref validate ./my-skill

# 验证所有 Skills
npx skills-ref validate .claude/skills/*/

获取帮助​

官方资源​

社区资源​

小结​

常见问题解决思路：

  1. 不触发 → 检查 description、关键词、目录位置
  2. 触发过多 → 使 description 更具体、添加排除条件
  3. 输出不佳 → 添加具体指令、示例、检查清单
  4. 验证失败 → 检查 YAML 格式、name 规范
  5. 看不到 Skill → 检查文件名、目录结构、信任设置
  6. 资源问题 → 检查路径、权限、文件存在
  7. 性能问题 → 优化大小、使用渐进式披露
  8. 兼容问题 → 使用标准格式、多工具测试