Claude code debug

Skill aiskillstore/marketplace/skills/0xdarkmatter/claude-code-debug

Security-audited skills for Claude, Codex & Claude Code. One-click install, quality verified.

Install

npx -y skills add aiskillstore/marketplace --skill claude-code-debug

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing 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.

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