Claude code debug
Skill bg-szy/TOP-SKILLS/skills/marketplace/claude-code-debug
全球最大的 Claude Code 技能聚合库 · 收录 3900+ 来自 12+ 来源的技能，提供在线搜索与趋势分析看板 / The world's largest Claude Code skill aggregation hub — 3900+ skills from 12+ sources with online search and trend dashboard
npx -y skills add bg-szy/TOP-SKILLS --skill claude-code-debugAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Troubleshoot Claude Code extensions and behavior. Triggers on: debug, troubleshoot, not working, skill not loading, hook not running, agent not found.
SKILL.md
2.7 KB, 615 tokens by cl100k_base, as published. Nobody here has run it
Claude Code Debug
Troubleshoot extensions, hooks, and unexpected behavior.
Quick Diagnostics
# 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
Common Issues
| Symptom | Quick Check |
|---|---|
| Skill not activating | Verify description has trigger keywords |
| Hook not running | Check chmod +x, run /hooks |
| Agent not delegating | Add "Use proactively" to description |
| MCP connection fails | Test server manually with npx |
| Permission denied | Check settings.json allow rules |
Debug Mode Output
claude --debug
# Shows:
# - Hook execution and errors
# - Skill loading status
# - Subagent invocations
# - Tool permission decisions
# - MCP server connections
Quick Fixes
Skill Not Loading
# 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
Hook Not Executing
# 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 Not Being Used
# 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"
Validation
# Run all validations
just test
# YAML validation only
just validate-yaml
# Name matching only
just validate-names
Official Documentation
- https://code.claude.com/docs/en/hooks - Hooks reference
- https://code.claude.com/docs/en/skills - Skills reference
- https://code.claude.com/docs/en/sub-agents - Custom subagents
- https://code.claude.com/docs/en/settings - Settings configuration
Additional Resources
./references/common-issues.md- Issue → Solution lookup table./references/debug-commands.md- All inspection commands./references/troubleshooting-flow.md- Decision tree
See Also: claude-code-hooks for hook debugging, claude-code-templates for correct structure
What ships with it: 1 file
79.3 KB alongside SKILL.md
- skill-report.json79.3 KB