How do I start debugging claude-code-debug?

Run claude --debug and use the Quick Diagnostics to inspect hooks, agents, memory, and config.

Why might a hook not be executing?

Possible causes include the hook script not being executable, misconfigured permissions, or a mismatch between skill hosting and hook location; verify chmod +x, re-test with sample input, and validate JSON syntax in settings.

What should I do if MCP server connection fails?

Test the server manually with npx and review your network/config; ensure the MCP URL/server is reachable and credentials, if any, are correct.

claude-code-debug

Scanned

npx machina-cli add skill aiskillstore/marketplace/claude-code-debug --openclaw

Files (1)

SKILL.md

2.7 KB

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

Source

git clone https://github.com/aiskillstore/marketplace/blob/main/skills/0xdarkmatter/claude-code-debug/SKILL.mdView on GitHub

Overview

Claude Code Debug helps you diagnose and resolve issues in Claude Code extensions, hooks, and subagents. It guides you from quick diagnostics to targeted fixes, reducing downtime when skills misbehave or don’t load. This skill consolidates commands, checks, and best practices to keep Claude Code working smoothly.

How This Skill Works

It provides a structured workflow: enable verbose debugging with claude --debug, inspect loaded hooks, agents, memory, and config, and map symptoms to known quick fixes. It highlights debug outputs, including hook execution, skill loading status, subagent invocations, tool permission decisions, and MCP server connections to pinpoint root causes.

When to Use It

Skill isn’t activating or loading
Hook isn’t executing or tests fail
Agent isn’t delegating or isn’t used as expected
MCP server/connection problems
Permission or configuration issues preventing debugging

Quick Start

Step 1: Run claude --debug to enable diagnostics
Step 2: Inspect state with /hooks, /agents, /memory, and /config
Step 3: Apply the relevant Quick Fixes and re-run validations (just test, just validate-yaml, just validate-names)

Best Practices

Always start with claude --debug and review Quick Diagnostics
Verify SKILL.md frontmatter and directory-name consistency
Ensure hook scripts are executable (chmod +x) and tested via /hooks
Check agent usage: ensure description includes 'Use proactively' or explicit request
Use the provided validation commands (just test, just validate-yaml, just validate-names) and consult the official docs

Example Use Cases

Diagnosing the Skill Not Activating case by confirming trigger keywords in the description
Fixing Hook Not Running by enabling executable and testing with a sample input
Resolving Agent Not Delegating by adding 'Use proactively' and explicitly requesting the agent
Addressing MCP connection failures by testing the server manually with npx
Handling Permission denied by adjusting settings.json allow rules

Frequently Asked Questions

Add this skill to your agents