金曜日の夜、スケジュール実行に使っているスキルの指示文を1行だけ直したことがあります。出力ログの形式を変える、ささやかな修正です。ところが翌朝のログを確認すると、実行結果は修正前の旧仕様のまま。ファイルは確かに保存されているのに、Claude Code が読んでいたのは「昨日の SKILL.md」でした。
個人開発で複数の自動化タスクを SKILL.md ベースで運用していると、この「直したのに反映されない」は意外なほど頻繁に起こります。原因はスキルの読み込みタイミングにあります。最近の Claude Code には .claude/skills 配下の自動ロードと /reload-skills コマンドが入り、再起動なしでスキルを差し替えられるようになりました。私が実運用で組み立てた差し替えの手順と、リロードが「効かない」ように見える落とし穴を順に整理します。
SKILL.md はセッション開始時に読み込まれる
スキルの実体は SKILL.md という Markdown ファイルですが、Claude Code がこれを参照するのは基本的にセッションの開始時です。起動時にスキル名と説明文の一覧（インデックス）が組み立てられ、タスクの内容に応じて該当スキルの本文が展開される、という二段階で動きます。
つまり、セッションが動いている間に SKILL.md を書き換えても、そのセッションが持っているインデックスは古いままです。挙動だけを見ると「ファイルを無視されている」ように感じますが、実際には「読み込み済みのスナップショットを参照し続けている」状態です。再起動すれば反映されるのはこのためです。
スキルの設計そのものについては、Claude Code カスタムスキル開発の実装パターン — SKILL.md 設計とテスト・配布 でまとめています。
.claude/skills 自動ロードで「配布」の工程が消えた
以前はスキルの配布にプラグインやマーケットプレイスを経由する前提があり、個人の作業用スキルには少し大げさな仕組みでした。現在はプロジェクトの .claude/skills 配下に置いたスキルが、マーケットプレイスを経由せずそのまま自動ロードされます。
私はこの変更を機に、スキルの正本を Git リポジトリで管理し、各プロジェクトの .claude/skills へ同期する形に揃えました。スキルはプロンプトであると同時に「運用手順書」でもあるので、差分履歴が残る Git 管理との相性は想像以上に良いです。いつどの指示をどう変えたかが追えるだけで、「なぜこの出力になったのか」を調べる時間が目に見えて減りました。
/reload-skills の射程 — 「次の発動」から効く
セッションを保ったままスキルを差し替えたいときは /reload-skills を実行します。編集 → /reload-skills → 次の発動から新版、という流れです。
ここに一つ、公式の説明だけでは気づきにくい点があります。リロードで更新されるのはスキルのインデックスと次回展開される本文であって、すでにそのセッションで展開済みの旧本文はコンテキストに残り続けることです。長いセッションの途中でリロードすると、直前まで参照していた旧指示と新しい指示が同居し、どちらに従った結果なのか判別しづらい状態になります。
そこで私の運用では、リロードは必ず「タスクの区切り」で行うと決めています。進行中の作業を一度完了させてから /reload-skills を打ち、新しいタスクとして仕切り直す。この一手間だけで、新旧の指示が混ざる問題はほとんど起きなくなりました。
無人実行は SessionStart フックで最新版を拾う
スケジュール実行のような無人運用では、そもそも /reload-skills を手で打てません。ここで使えるのが SessionStart フックです。セッション開始時にスキルの同期処理を走らせ、フックの出力で reloadSkills: true を返すと、取得し直した最新のスキルを読み込ませられます。
次のスクリプトは、スキルの正本リポジトリを起動時に同期してから読み込ませる例です。
#!/bin/bash
# .claude/hooks/session-start-sync.sh
# スキル正本リポジトリを起動時に同期してから読み込ませる
git -C "$HOME/dev/skills-repo" pull --rebase --quiet
rsync -a --delete "$HOME/dev/skills-repo/skills/" ".claude/skills/"
echo '{"reloadSkills": true}'settings.json 側には次のように登録します。
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "bash .claude/hooks/session-start-sync.sh"
}
]
}
]
}
}注意したいのは、クラウドストレージの同期機能でスキルを配っている場合です。同期が完了する前にセッションが起動すると、ローカルにはまだ旧版しかありません。フックは「その時点でローカルにあるもの」を読むだけなので、これは仕組みだけでは防ぎきれず、私は次に紹介する版番号チェックで検出する形にしています。
無人実行まわりの設計は Claude Code Skill を無人で動かす設計 — 許可ダイアログで止まらない3つの実装パターン でも扱っています。
どの版が効いているかを版番号で見える化する
「直したのに反映されない」を根本からなくしてくれたのは、リロードの仕組みそのものより、どの版のスキルが効いているかをログで確認できるようにしたことでした。やることは2つだけです。
まず、SKILL.md の冒頭コメントに版番号と日付を書きます。
<!-- version: 2026-06-13.1 -->
# article-publisher次に、スキルの手順の先頭へ「この version 行を実行ログに出力する」ステップを入れます。
grep -m1 'version:' .claude/skills/article-publisher/SKILL.mdこれだけで、毎回の実行ログの先頭に「どの版で動いたか」が残ります。挙動が旧仕様に見えたら、まずログの版番号を確認する。版が古ければ同期かリロードの問題、版が新しいのに挙動が古ければ指示文そのものの問題、と切り分けが一直線になります。私自身、この2行を入れてからは「反映されたはず」を推測で語ることがなくなりました。
次の一歩 — version 行を1つ足すところから
差し替え運用は、/reload-skills や SessionStart フックといった仕組みを覚えるより先に、「いまどの版が効いているか」を見えるようにするのが近道です。お使いのスキルの SKILL.md に version 行を1つ足し、実行ログへ出力してみてください。反映タイミングの挙動が一気に観察しやすくなります。日々の開発でどのスキルを手元に残すかという観点は Claude Code Skills を毎日の開発に組み込むときに、私が見ている 5 つの選定軸 にまとめています。同じように SKILL.md ベースの自動化を運用している方の参考になれば幸いです。