claude-code-debug
Troubleshoot Claude Code extensions and behavior. Triggers on: debug, troubleshoot, not working, skill not loading, hook not running, agent not found.
When & Why to Use This Skill
The Claude Code Debug skill is a specialized diagnostic utility designed to troubleshoot and resolve issues within the Claude Code CLI environment. It provides developers with a systematic approach to identify and fix problems related to extension loading, hook execution, agent delegation, and MCP server connections. By leveraging built-in debug modes and validation commands, it ensures a seamless development experience when building custom Claude Code extensions.
Use Cases
- Diagnosing why a custom skill or extension is not activating by verifying YAML frontmatter, directory structures, and trigger keywords.
- Troubleshooting shell hooks that fail to execute by checking file permissions (chmod +x) and validating JSON communication syntax.
- Resolving agent discovery issues where specific sub-agents are not being triggered or found by the main Claude Code CLI.
- Debugging Model Context Protocol (MCP) connection failures and permission denied errors within the settings.json configuration.
- Using the --debug mode to inspect real-time tool permission decisions and sub-agent invocation logs.
| name | claude-code-debug |
|---|---|
| description | "Troubleshoot Claude Code extensions and behavior. Triggers on: debug, troubleshoot, not working, skill not loading, hook not running, agent not found." |
| compatibility | "Claude Code CLI" |
| allowed-tools | "Bash Read" |
| depends-on | [] |
| related-skills | [claude-code-hooks, claude-code-headless, claude-code-templates] |
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