AgentSkillsCN

claude-code-debug

以编程方式运行 Claude Code，无需交互式 UI。可通过“无头模式”、“CLI 自动化”、“--print”、“输出格式”、“stream-json”、“CI/CD”、“脚本编写”等指令触发。

SKILL.md
--- frontmatter
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

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

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

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