/skill-doctor は、作ったSkillが一覧に出ない、呼んでも動かない、話題を振っても自動発動しないといった症状の原因を、7つのチェック項目に沿って機械的に切り分けるClaude Code Skillです。原因の候補を頭の中で総当たりする代わりに、上から順に確認するだけで大半の「動かない」の原因にたどり着けます。

何を解決するSkillか

Skillが認識されない時、原因は症状によって層が違います。一覧に名前すら出ないなら読み込み以前の問題、一覧には出るのに期待どおり動かないなら中身の問題、呼べば動くのに自動発動だけしないならdescriptionの問題です。この切り分けを毎回頭でやり直すのは手間なうえ、確認漏れも起きます。

このSkillは、当メディアの記事「Claude Code Skillが認識されない時に見る7つの確認点」で整理した確認手順を、そのままSkillとして実行できる形にしたものです。記事を読みながら手作業で1つずつ確認する代わりに、対象のSKILL.mdを指定するだけで7項目の判定結果を一覧で受け取れます。

仕様

コマンド/skill-doctor
入力診断したいSkillの名前、またはSKILL.mdのファイルパス
出力7項目（置き場所／ファイル名／フロントマター構文／name一致／description具体性／セッション再読み込み／文字コード）のOK・NG・確認不可判定と、NG項目への修正案
前提Claude Code（Skillが使えるプラン）。追加のツール権限は不要

ダウンロード

Skill本体（SKILL.md）を無料で配布しています。zipを展開し、フォルダごと .claude/skills/ に置くと /skill-doctor で使えます。

/skill-doctor をダウンロード（無料）

導入手順

配布ファイルを解凍し、プロジェクトのSkillフォルダに置きます。

your-project/
└── .claude/
    └── skills/
        └── skill-doctor/
            └── SKILL.md

配置後、新規セッションで/skill-doctorと入力し、診断したいSkill名またはパスを伝えれば診断が始まります。

実際の使用例

自動発動しないSkillを診断させた場合のやり取りの例です。

> /skill-doctor my-skill が話しかけても発動しない

my-skill/SKILL.md を確認します。

1. 置き場所: OK
2. ファイル名: OK
3. フロントマター構文: OK
4. name一致: OK
5. description具体性: NG
   現在の記述「便利な支援スキル」はトリガー条件が書かれていません。
   修正案: 「請求書PDFからデータを抽出するよう頼まれたときに使う」のように、
   いつ使うかとユーザーが実際に打ちそうな語を含めてください。
6. セッション再読み込み: 確認不可
   直近でこのSkillを追加・修正しましたか？（はい/いいえ）
7. 文字コード: OK

自動発動しない症状は、5のdescriptionが原因である可能性が高いです。

7項目のうちどれがNGかが一目でわかるため、原因の見当をつける時間が要りません。

使ってわかった向き不向き

向いている場面

  • 新しいSkillを作った直後の動作確認。公開前のセルフチェックとして一度通しておくと、後からの「動かない」に悩む時間が減ります。
  • 複数人でSkillを量産している現場。作った本人以外がレビューする際、判定基準が同じなので確認のばらつきが出ません。

向いていない場面

  • SKILL.md本文の手順やロジックの品質評価。このSkillは「認識・発動されるかどうか」だけを診断します。手順の設計や完了条件の妥当性を見るものではありません。
  • MCPサーバーやプラグイン由来のツールの不具合。診断対象はSKILL.mdの読み込みに関する問題に限定されます。

カスタマイズのヒント

SKILL.mdはただのMarkdownなので、自分の運用に合わせて書き換えられます。よく効く追記は次の2つです。

  • 自社のSkill配置規約（命名規則やディレクトリ構成の独自ルール）がある場合、チェック項目1・4にその規約を明記する
  • 診断結果をチームで共有する運用なら、報告フォーマットに「診断日」「診断者」を追記する一文を足す

Skillの書き方そのものを詳しく知りたい方は「機能するSkillの書き方」を、descriptionの設計に絞って読みたい方は「Skillが認識されない時に見る7つの確認点」をご覧ください。