claude-code-debug
Troubleshoot Claude Code extensions and behavior. Triggers on: debug, troubleshoot, not working, skill not loading, hook not running, agent not found.
Best use case
claude-code-debug is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Troubleshoot Claude Code extensions and behavior. Triggers on: debug, troubleshoot, not working, skill not loading, hook not running, agent not found.
Teams using claude-code-debug should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/claude-code-debug/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How claude-code-debug Compares
| Feature / Agent | claude-code-debug | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Troubleshoot Claude Code extensions and behavior. Triggers on: debug, troubleshoot, not working, skill not loading, hook not running, agent not found.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
AI Agents for Coding
Browse AI agent skills for coding, debugging, testing, refactoring, code review, and developer workflows across Claude, Cursor, and Codex.
ChatGPT vs Claude for Agent Skills
Compare ChatGPT and Claude for AI agent skills across coding, writing, research, and reusable workflow execution.
SKILL.md Source
# Claude Code Debug
Troubleshoot extensions, hooks, and unexpected behavior.
## Quick Diagnostics
```bash
# 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
```bash
claude --debug
# Shows:
# - Hook execution and errors
# - Skill loading status
# - Subagent invocations
# - Tool permission decisions
# - MCP server connections
```
## Quick Fixes
### Skill Not Loading
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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