CtrlK
BlogDocsLog inGet started
Tessl Logo

claude-code-debug

Troubleshoot Claude Code extensions and behavior. Triggers on: debug, troubleshoot, not working, skill not loading, hook not running, agent not found.

Invalid
This skill can't be scored yet
Validation errors are blocking scoring. Review and fix them to unlock Quality, Impact and Security scores. See what needs fixing →
SKILL.md
Quality
Evals
Security

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

SymptomQuick Check
Skill not activatingVerify description has trigger keywords
Hook not runningCheck chmod +x, run /hooks
Agent not delegatingAdd "Use proactively" to description
MCP connection failsTest server manually with npx
Permission deniedCheck 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

Repository
NeverSight/skills_feed
Commit

5342bca

Last updated
Created

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill