Claude Code でスキルはいつ自動反映される？/reload-skills の使い所を整理してみた
どうも！オペ部の西村祐二です！
Claude Code を触っていると、スキルを追加・更新したときに「これ、今のセッションにもう反映されているのかな？」と気になる場面があります。
Claude Code にはもともとスキルの自動検出・hot-reload 機能があり、~/.claude/skills やプロジェクト配下の .claude/skills に置いたスキルは、基本的にはセッションを再起動しなくても利用できるようになっています。
そんな中、Claude Code v2.1.152 で /reload-skills コマンドが追加されていました。
/reload-skills は、現在のセッションを閉じずにスキルディレクトリを再スキャンするためのコマンドです。通常は自動検出に任せればよさそうですが、変更がうまく拾われているか確認したいときや、明示的に再スキャンしたいときには便利そうです。
とはいえ、毎回スキルを追加・更新するたびに /reload-skills を実行する必要があるわけではありません。Claude Code は通常のメッセージ処理時にスキルディレクトリの変更を検出するため、多くのケースでは自動で反映されます。
この記事では、実際に /reload-skills を試しながら、
- どの変更は自動で反映されるのか
- どの場面で
/reload-skillsが役立つのか - 既存の hot-reload 機能と何が違うのか
を整理してみます。
スキルの自動反映はいつ追加された機能なのか
まず時系列を確認しておくと、スキルの自動 hot-reload 自体は /reload-skills より前から存在しています。Claude Code の changelog をたどると、おおむね次のような流れになっています。
- v2.1.0: automatic skill hot-reload を追加。
~/.claude/skillsまたは.claude/skillsで作成・変更したスキルが、セッションを再起動しなくても利用できるようになりました。 - v2.1.32:
--add-dirで追加したディレクトリ内の.claude/skills/も自動ロードの対象になりました。監視対象のスキルディレクトリの範囲が広がった形です。 - v2.1.152: 今回見る
/reload-skillsコマンドが追加されました。 - v2.1.157:
.claude/skillsディレクトリに配置したプラグインが、マーケットプレイスへの登録なしに自動的に読み込まれるようになりました。これにより、プロジェクト配下の.claude/skills/にプラグインを置くだけで利用できます。
なお、/reload-skills と同じ v2.1.152 では、SessionStart フックからスキルディレクトリを再スキャンする仕組みも入っていますが、本記事では /reload-skills 本体の使い所に絞ります。
その後の v2.1.174 では、hot-reload で 1 つのスキルだけが変わったときに、スキル一覧全体を再通知していた挙動が修正され、変更されたスキルだけが再通知されるようになりました。自動反映が動いているときの体感にも関わる改善です。
こうして並べてみると、/reload-skills は「自動検出がなかった頃の代替機能」というより、もともとある自動 hot-reload を補助する、手動再スキャン用のコマンドと捉えるのがよさそうです。
今回やること
この記事で分かること:
- 監視対象のスキルディレクトリで、何が自動反映されるのか
/reload-skillsを実行すると何が起きるのか- 自動 hot-reload と
/reload-skillsをどう使い分けると整理しやすいか
前提条件
動作環境:
- OS: macOS
- ツール / バージョン: Claude Code 2.1.177
前提:
- Claude Code のスキル機能を使っている
- スキルディレクトリ（
.claude/skills/または~/.claude/skills/）にスキルファイルがある
どの変更が自動で反映されるのか
公式ドキュメントの Live change detection では、Claude Code がスキルディレクトリのファイル変更を監視していると説明されています。監視対象は次の 3 か所です。
~/.claude/skills/- プロジェクト直下の
.claude/skills/ --add-dirで追加したディレクトリ内の.claude/skills/
これらの配下であれば、スキルの追加・編集・削除はセッションを再起動しなくても反映されます。たとえば作業中に SKILL.md の本文や description を書き換えた場合も、その変更は現在のセッションで拾われます。
いくつか補足しておくと、
- 自動反映の対象は
SKILL.mdのテキストです。スキルフォルダがプラグインを兼ねていてhooks/や.mcp.jsonなどを含む場合、それらの変更は別途/reload-pluginsが必要だと案内されています。なお v2.1.157 からは、.claude/skills/に配置したプラグインはマーケットプレイスなしでセッション開始時に自動ロードされるようになりました。ただしこれはセッション開始時の読み込みの話であり、セッション中にプラグインファイルを変更した場合は引き続き/reload-pluginsが必要です。 - 前述の v2.1.174 の修正により、1 つのスキルを編集しただけでスキル一覧が丸ごと再通知されることはなくなり、変更されたスキルだけが再通知されます。
つまり、監視対象ディレクトリ配下での SKILL.md の追加・編集・削除であれば、反映のためだけに毎回 /reload-skills を実行する必要はなさそうです。
/reload-skills が役立つ場面
ここまでの通り、基本は自動検出に任せられます。そのうえで /reload-skills が役立つのは、変更を自動反映に頼らずその場で確実に読み直したいときや、いま何件のスキルが読み込まれているかを確認したいときです。
実際にコマンドを実行すると、Claude Code がスキルディレクトリを再スキャンし、結果がレポートとして表示されます。手元の Claude Code 2.1.177 では、次のような形式のメッセージが返ってきます。
Reloaded skills: 25 skills available (2 added, 1 removed)
変更がなかった場合は、件数のかわりに (no changes) が表示されます。
Reloaded skills: 25 skills available (no changes)
利用可能なスキルの総数と、今回の再スキャンで追加・削除された件数がまとめて分かるので、「いま認識されているスキルが期待どおりか」を確認する用途に向いていそうです。
自動 hot-reload との違いという観点で見ると、/reload-skills は監視に任せて待つのではなく、同じ再スキャンを手動で即座に走らせ、その結果を件数つきで返してくれるコマンド、という位置づけになります。自分の中では次のように整理しておくと使い分けやすそうです。
| やりたいこと | 基本の考え方 |
|---|---|
既存の SKILL.md を編集する |
自動検出に任せる |
| 監視対象ディレクトリにスキルを追加・削除する | 自動検出に任せる |
| 変更をその場で即時に反映・確認したい | /reload-skills を実行する |
| 読み込み件数や追加・削除件数を確認したい | /reload-skills のレポートを見る |
セッション開始時になかったトップレベル skills ディレクトリを新設した |
Claude Code を再起動する |
実際に試してみる
1. スキルファイルを作成または編集する
動作確認用に、最小構成のスキルを 1 つ用意します。新しいスキルを追加する場合の最小構成は次のとおりです。
.claude/skills/
└── my-skill/
└── SKILL.md
SKILL.md の frontmatter に name と description を書くと、Claude Code がスキルとして認識します。
---
name: my-skill
description: |
このスキルを呼び出す状況と目的を書く。
「〜して」「〜を確認して」などのキーフレーズを含めると精度が上がる。
---
# My Skill
スキルの指示内容をここに書く。
監視対象のスキルディレクトリ配下であれば、ここでの追加や編集はそのままセッション内で拾われます。/reload-skills は、その反映をあえて手動で即座に走らせて確認したいときに使う、という位置づけになります。
2. /reload-skills を実行する
Claude Code のセッション内でコマンドを入力します。
/reload-skills
実行すると、スキルディレクトリが再スキャンされ、Reloaded skills: ... のレポートが表示されます。追加・削除した件数が想定どおりかをここで確認できます。
3. 動作確認する
スキルの description に書いたキーフレーズを入力して、スキルが呼び出されるかを確認します。
期待する結果:
- 新しく追加したスキルが呼び出せるようになる
- 編集したスキルの内容がセッション再起動なしに反映される
つまずきポイント
/reload-skills を実行しても新しいスキルが使えない
原因: スキルのディレクトリ名やファイルの位置が、Claude Code の読み込むパスと一致していない場合があります。Claude Code は .claude/skills/<name>/SKILL.md をエントリポイントとして読み込むため、ネストが深い場所に置くと認識されません。また、Live change detection の説明では、セッション開始時に存在しなかった最上位の skills ディレクトリを新しく作った場合、そのディレクトリを監視対象にするために Claude Code の再起動が必要だとされています。この場合は /reload-skills ではなく再起動が必要です。
対処: SKILL.md が skills/<name>/SKILL.md の直下にあるかを確認します。
fd SKILL.md .claude/skills ~/.claude/skills
まとめ
/reload-skills は、現在のセッションを閉じずにスキルディレクトリを明示的に再スキャンし、利用可能なスキル数と追加・削除件数をレポートしてくれるコマンドです。
既存スキルの編集や、監視対象ディレクトリ配下へのスキル追加・削除は Live change detection で自動反映されるため、普段の SKILL.md 調整で毎回実行するものではなさそうです。一方で、変更を待たずにその場で確実に読み直したいときや、いま何件のスキルが認識されているかを確認したいときには、手動再スキャンとレポートの両方を兼ねる /reload-skills が役立ちそうだと感じました。
自分の中では「通常は自動検出、その場で確実に反映・確認したいときだけ /reload-skills」くらいに整理しておくと、スキル運用が少し楽になりそうです。
誰かの参考になれば幸いです。
参考リンク:
