claude-code-debug_skill

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