mcpField
C
claude-code-debug

claude-code-debug

github.com/0xdarkmatterAgent 工作流7853 次安装2 周前更新
代码仓库

关于 claude-code-debug

这项技能用于排查 Claude Code 的扩展、Hook、Agent、技能、权限及 MCP 连接问题，提供诊断命令、常见检查项和验证步骤，帮助定位异常行为。

主要功能

  1. 01检查调试输出和配置
  2. 02检查 Hook、Agent 与记忆
  3. 03排查技能和 Hook 加载问题
  4. 04测试 MCP 服务连接
  5. 05运行 YAML 和命名验证

适用场景

  1. 01调查技能无法加载的原因
  2. 02诊断 Hook 未运行的问题
  3. 03检查 Agent 未委派的原因
  4. 04排查 MCP 连接失败

MCP 相关

该技能帮助诊断 Claude Code 中的 MCP 服务连接故障，包括建议使用 `npx` 手动测试服务。它还说明调试输出可显示 MCP 服务连接情况。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/0xdarkmatter/claude-mods --skill claude-code-debug

安装后在 Claude Code 中输入/claude-code-debug确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
.gitkeep
references/
troubleshooting-flow.md
debug-commands.md
common-issues.md
scripts/
.gitkeep

详细介绍

Claude Code 调试

排查扩展、钩子和意外行为。

快速诊断

# Enable debug mode
claude --debug

# Check loaded extensions
/hooks        # View registered hooks
/agents       # View available agents
/memory       # View loaded memory files
/config       # View current configuration

常见问题

症状快速检查
Skill 未激活确认描述中包含触发关键词
钩子未运行检查 chmod +x，运行 /hooks
Agent 未委派任务在描述中添加“主动使用”
MCP 连接失败使用 npx 手动测试服务
权限被拒绝检查 settings.json 中的允许规则

调试模式输出

claude --debug
# Shows:
# - Hook execution and errors
# - Skill loading status
# - Subagent invocations
# - Tool permission decisions
# - MCP server connections

快速修复

Skill 未加载
# Check structure
ls -la .claude/skills/my-skill/
# Must have: SKILL.md

# Verify YAML frontmatter
head -10 .claude/skills/my-skill/SKILL.md
# Must start/end with ---

# Check name matches directory
grep "^name:" .claude/skills/my-skill/SKILL.md
钩子未执行
# Make executable
chmod +x .claude/hooks/my-hook.sh

# Test manually
echo '{"tool_name":"Bash"}' | .claude/hooks/my-hook.sh
echo $?  # Check exit code

# Verify JSON syntax
jq '.' ~/.claude/settings.json
Agent 未被使用
# Check file location
ls ~/.claude/agents/
ls .claude/agents/

# Verify description includes "Use for:" or "Use proactively"
grep -i "use" agents/my-agent.md | head -5

# Explicitly request
# "Use the my-agent agent to analyze this"

验证

# Run all validations
just test

# YAML validation only
just validate-yaml

# Name matching only
just validate-names

官方文档

其他资源

  • ./references/common-issues.md - 问题 → 解决方案查询表
  • ./references/debug-commands.md - 所有检查命令
  • ./references/troubleshooting-flow.md - 决策树

另请参阅： claude-code-hooks，用于钩子调试；claude-code-templates，用于正确的结构

评论

支持 Markdown