🛠️ 開発・MCP コミュニティ

claude-code-debug

Claude Code拡張機能のデバッグやトラブルシューティングを行い、動作しない問題やエラーを解決するSkill。

📜 元の英語説明(参考)

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

🇯🇵 日本人クリエイター向け解説

一言でいうと

Claude Code拡張機能のデバッグやトラブルシューティングを行い、動作しない問題やエラーを解決するSkill。

※ jpskill.com 編集部が日本のビジネス現場向けに補足した解説です。Skill本体の挙動とは独立した参考情報です。

⬇ このSkillをダウンロード(.skill) 元のソースを見る ↗

⚠️ ダウンロード・利用は自己責任でお願いします。当サイトは内容・動作・安全性について責任を負いません。

🎯 このSkillでできること

下記の説明文を読むと、このSkillがあなたに何をしてくれるかが分かります。Claudeにこの分野の依頼をすると、自動で発動します。

📦 インストール方法 (3ステップ)

1. 上の「ダウンロード」ボタンを押して .skill ファイルを取得
2. ファイル名の拡張子を .skill から .zip に変えて展開(macは自動展開可)
3. 展開してできたフォルダを、ホームフォルダの .claude/skills/ に置く
- · macOS / Linux: ~/.claude/skills/
- · Windows: %USERPROFILE%\.claude\skills\

Claude Code を再起動すれば完了。「このSkillを使って…」と話しかけなくても、関連する依頼で自動的に呼び出されます。

詳しい使い方ガイドを見る →

最終更新: 2026-05-17
取得日時: 2026-05-17
同梱ファイル: 1

📖 Skill本文(日本語訳)

※ 原文(英語/中国語)を Gemini で日本語化したものです。Claude 自身は原文を読みます。誤訳がある場合は原文をご確認ください。

Claude コードデバッグ

拡張機能、フック、予期せぬ動作のトラブルシューティングを行います。

クイック診断

# デバッグモードを有効にする
claude --debug

# ロードされた拡張機能を確認する
/hooks        # 登録されているフックを表示
/agents       # 利用可能なエージェントを表示
/memory       # ロードされたメモリファイルを表示
/config       # 現在の設定を表示

よくある問題

症状	クイックチェック
スキルがアクティブにならない	説明にトリガーキーワードがあるか確認する
フックが実行されない	`chmod +x` を確認し、`/hooks` を実行する
エージェントが委任しない	説明に「Use proactively」を追加する
MCP 接続が失敗する	`npx` でサーバーを手動でテストする
権限が拒否される	settings.json の許可ルールを確認する

デバッグモードの出力

claude --debug
# 表示されるもの:
# - フックの実行とエラー
# - スキルのロード状況
# - サブエージェントの呼び出し
# - ツールの権限決定
# - MCP サーバー接続

クイックフィックス

スキルがロードされない

# 構造を確認する
ls -la .claude/skills/my-skill/
# 必須: SKILL.md

# YAML フロントマターを確認する
head -10 .claude/skills/my-skill/SKILL.md
# --- で開始/終了する必要があります

# 名前がディレクトリと一致するか確認する
grep "^name:" .claude/skills/my-skill/SKILL.md

フックが実行されない

# 実行可能にする
chmod +x .claude/hooks/my-hook.sh

# 手動でテストする
echo '{"tool_name":"Bash"}' | .claude/hooks/my-hook.sh
echo $?  # 終了コードを確認する

# JSON 構文を確認する
jq '.' ~/.claude/settings.json

エージェントが使用されない

# ファイルの場所を確認する
ls ~/.claude/agents/
ls .claude/agents/

# 説明に「Use for:」または「Use proactively」が含まれているか確認する
grep -i "use" agents/my-agent.md | head -5

# 明示的にリクエストする
# "Use the my-agent agent to analyze this"

バリデーション

# すべてのバリデーションを実行する
just test

# YAML バリデーションのみ
just validate-yaml

# 名前の一致のみ
just validate-names

公式ドキュメント

https://code.claude.com/docs/en/hooks - フックのリファレンス
https://code.claude.com/docs/en/skills - スキルのリファレンス
https://code.claude.com/docs/en/sub-agents - カスタムサブエージェント
https://code.claude.com/docs/en/settings - 設定の構成

追加リソース

./references/common-issues.md - 問題 → 解決策のルックアップテーブル
./references/debug-commands.md - すべての検査コマンド
./references/troubleshooting-flow.md - 意思決定ツリー

参照: フックのデバッグについては claude-code-hooks、正しい構造については claude-code-templates を参照してください。

📜 原文 SKILL.md(Claudeが読む英語/中国語)を展開

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