home / skills / 0xdarkmatter / claude-mods / claude-code-debug

claude-code-debug skill

safe

This skill helps you troubleshoot Claude Code extensions and hooks, diagnose failures, and restore proper agent and hook operation.

npx playbooks add skill 0xdarkmatter/claude-mods --skill claude-code-debug

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

2.7 KB

---
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

```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

Overview

This skill helps troubleshoot Claude Code extensions, hooks, agents, and runtime behavior to restore expected operation quickly. It provides targeted diagnostics, checks common failure points, and suggests concrete commands and fixes for configuration, permissions, and delegation issues. Use it to pinpoint why a hook or agent is not running and to validate your setup.

How this skill works

The skill inspects runtime debug output, registered hooks, available agents, memory files, and current configuration. It runs quick diagnostic commands to reveal permission problems, JSON/YAML syntax errors, missing executables, and agent description issues that prevent delegation. It also guides manual tests for hook execution and server connectivity.

When to use it

A skill or hook is not activating or responding to triggers
An agent is not being selected or delegated to as expected
Hooks run but return errors or no output
Permission denied or executable bit issues for hook scripts
MCP/server connection failures or tool permission denials

Best practices

Enable debug mode to capture detailed load and execution logs before reproducing the issue
Keep hook scripts executable and test them with a sample JSON payload locally
Include clear trigger keywords and explicit delegation hints like "Use proactively" in agent descriptions
Validate JSON and YAML files after edits to avoid syntax-related failures
Run targeted validation commands regularly to catch name, structure, and schema mismatches

Example use cases

Investigate why a hook registered for a specific trigger never runs and confirm executable permissions
Diagnose why a custom agent is ignored and update its description to encourage delegation
Verify that the runtime is connecting to an MCP server and identify network or auth issues
Run a full validation suite after adding new skills to catch naming and frontmatter problems
Test a hook end-to-end by piping a sample payload and checking the exit code and output

FAQ

What should I enable first when debugging?

Turn on debug mode to capture detailed logs of skill loading, hook execution, and tool permission decisions.

How do I test a hook script manually?

Make the script executable and pipe a representative JSON payload into it, then check the exit code and output.