用途
Claude Code Debug 用于排查 Claude Code 扩展与异常行为，覆盖扩展（extensions）、钩子（hooks）以及非预期表现的定位与修复。该技能在出现 debug、troubleshoot、not working、skill not loading、hook not running、agent not found 等触发词时启用。
主要能力
- 快速诊断：提供调试模式与检查命令。
- 启用调试模式：claude --debug
- 查看已注册钩子：/hooks
- 查看可用智能体：/agents
- 查看已加载记忆文件：/memory
- 查看当前配置：/config
- 常见问题速查表（症状 → 快速检查）：
- 技能未激活：确认描述中包含触发关键词。
- 钩子未运行：检查 chmod +x，运行 /hooks。
- 智能体未委派：在描述中加入 "Use proactively"。
- MCP 连接失败：用 npx 手动测试服务器。
- 权限被拒：检查 settings.json 的 allow 规则。
- 调试模式输出说明：claude --debug 会显示钩子执行与错误、技能加载状态、子智能体调用、工具权限决策、MCP 服务器连接。
使用方式
- 技能未加载时：
- 检查结构：ls -la .claude/skills/my-skill/（必须包含 SKILL.md）
- 验证 YAML frontmatter：head -10 .claude/skills/my-skill/SKILL.md（必须以 --- 开始和结束）
- 检查名称与目录一致：grep "^name:" .claude/skills/my-skill/SKILL.md
- 钩子未执行时：
- 赋予可执行权限：chmod +x .claude/hooks/my-hook.sh
- 手动测试：echo '{"tool_name":"Bash"}' | .claude/hooks/my-hook.sh，并用 echo $? 检查退出码
- 验证 JSON 语法：jq '.' ~/.claude/settings.json
- 智能体未被使用时：
- 检查文件位置：ls ~/.claude/agents/ 与 ls .claude/agents/
- 验证描述包含 "Use for:" 或 "Use proactively"：grep -i "use" agents/my-agent.md | head -5
- 显式请求："Use the my-agent agent to analyze this"
- 验证命令：
- 运行全部验证：just test
- 仅 YAML 验证：just validate-yaml
- 仅名称匹配验证：just validate-names
适用场景
适用于开发者在使用 Claude Code 扩展、钩子、子智能体、MCP 服务器时，遇到加载失败、执行异常、委派失效、连接失败或权限问题等排查场景。
限制
资料未提供关于该技能的具体实现细节、适用范围之外的功能、性能或效果说明。
官方文档
- Hooks 参考：https://code.claude.com/docs/en/hooks
- Skills 参考：https://code.claude.com/docs/en/skills
- 自定义子智能体：https://code.claude.com/docs/en/sub-agents
- 设置配置：https://code.claude.com/docs/en/settings
附加资源
- ./references/common-issues.md：问题 → 解决方案速查表
- ./references/debug-commands.md：全部检查命令
- ./references/troubleshooting-flow.md：决策树
另见：claude-code-hooks（用于钩子调试）、claude-code-templates（用于正确结构）。