Claude Code を使い始めて、skills が少しずつ溜まってきました。今のところユーザーグローバル(~/.claude/skills/)に4つ、リポジトリ内(.claude/skills/)に8つ。同名のものもあるので実効は8個ですが、ファイルとしては合計12個になります。特に rspec はフィードバックの追記が積み重なって 29KB ほど。
増えてくると気になるのが、これらの skills が本当に効いているのか、どうやって確認するかという話です。仕組みとして検証の枠組みを作るべきか、運用で済ませられるのか。今回はこれを考えてみます。
- 現状の運用で機能していること
- それでも気になる論点
- 公式機能はまだ未実装
- AIに依頼してhookを作ってみた
- 動かしてみて気付いたhookの特性
- 観測できるもの、できないもの
- 自分のskillsを見直してみた
- 他の選択肢の存在
- バージョンアップ時の棚卸し
- まとめ
現状の運用で機能していること
正直なところ、自分の運用では困っていません。やっていることは単純で、AIコーディングをしている中で「あ、ここの規約が抜け落ちた」「この書き方は古い」と気付いたら、AIに「学習できることはありましたか?」と聞きます。AIが気付きを言語化して、関連する skill に追記する。
これは、以前ハーネスについて書いた記事で書いた「運用しながらハーネスを育てる」を、シンプルに実践している形です。
この運用は、いくつかの理由で機能しています。
- AIが自分で書いているので、AIの能力に合った内容になる
- 抜け落ちが現場で気付かれて、追記される(自然なフィードバックループ)
- 効きが悪くなったら再学習で更新される
- モデル切り替え(Sonnet 4.6 / Opus 4.7)も同じ運用で対応
つまり、明示的な検証の仕組みがなくても、運用の中で自然に検証が組み込まれている状態です。
それでも気になる論点
1. 参照頻度を可視化できないか?
skills が増えてくると、「どれが使われているか」を把握しにくくなる。今は目視で追えるけど、20個、30個と増えたら、把握しきれなくなりそう。
2. バージョンアップ時に古い skill が邪魔しないか?
モデルがバージョンアップしたとき、旧モデル向けの工夫が新モデルの邪魔をする可能性があります。以前書いた「ガードレールと能力補完パッチを区別する」という話の延長で、棚卸しがいずれ必要になりそう。
これらに対して、明示的な仕組みを作るべきか、運用で対応できるかを考えました。
公式機能はまだ未実装
調べてみたら、「skill の呼び出しを記録する公式機能」は、まだ Claude Code に実装されていないことが分かりました。
GitHub に Issue #35319(2026年3月)があって、「skills が67個から183個に4週間で増えた」「どれが使われているか分からない」という困りごとが、まさに同じ問題として挙がっています。組織レベルで運用している人たちが、本気で困っている話です。
ただ、hook で近似することは今でもできるらしい。Anthropic 社内でも PreToolUse hook で skill 使用をログしている、という話が Medium 記事にも出ていました。
AIに依頼してhookを作ってみた
仕組みを公式が出してくれるのを待つよりは、自分の規模に合った軽量なものを試してみたい。そう思って、AIに依頼してみました。
「skill を読み込んだら、ログファイルに記録して。毎回やって欲しい。どこに出力されますか?」
「リポジトリ内に.claude/skills/があった場合は、そっちも対象になる?両方に同じものがあった場合は?」
そうしたらAIが、設定スコープ(全プロジェクト共通か特定プロジェクトか)、出力先パス、トリガー(Skill ツール呼び出し時か /コマンド 入力時か)を逐一質問してから、PreToolUse hook を作り上げてくれました。最終的にできたのは:
- 出力先:
~/.claude/logs/skill-loads.log - 設定ファイル:
~/.claude/settings.jsonのhooks.PreToolUseに matcherSkillで追加 - ログ形式(タブ区切り):
timestamp / skill名 / args / cwd / session_id - jq が stdin の hook 入力 JSON から各値を抽出して追記
仕組みとしては、Claude が Skill ツールでスキルを呼び出すたびに PreToolUse が発火して、jq でログを抽出して書き込むだけ。シェルコマンドだけで完結する軽量な仕組みです。
これは、以前書いた「最小から始める」の実践でもあります。重い検証システムを作るのではなく、まずログを取るだけの最小構成で動かす。
% cat ~/.claude/logs/skill-loads.log 2026-05-09T07:38:41 skill=update-config args=スキル読み込み時のログ session=test-123 2026-05-09T08:00:58 skill=review cwd=/Users/xxx/workspace/yyy args= session=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
動かしてみて気付いたhookの特性
hookはモデル非依存
Opus で hook を設定しましたが、Sonnet や Haiku でも同じように動きます。「Skill ツールが呼ばれたら hook が発火する」という挙動は、モデルに関係なく、Claude Code 本体が settings.json を読んで実行する仕組みだからです。
これは、hook という仕組みの強みが具体的に分かる例だと思いました。CLAUDE.md や skills はモデルが読んで解釈するので、モデル進化で挙動が変わる。一方、hook はハーネス本体が機械的に実行するので、モデルが何をしようと安定して動きます。
hookの設置場所も3階層
skills と同じく、hook も3階層の設置場所があります。
~/.claude/settings.json: 個人共通.claude/settings.json: プロジェクト(チーム共有、commit).claude/settings.local.json: プロジェクト個人(gitignore)
ただ、hook は「マージ」される点が違います。skills は同名だと優先順位で1つが採用されるけど、hook は両方発火する。重複ログに注意が必要です。
skills の参照ログ用の hook は、個人共通(~/.claude/settings.json)に置けば、全プロジェクトで自分のログが溜まります。チーム全員でこのプロジェクトの参照ログを取りたいなら、リポジトリ内(.claude/settings.json)に hook を入れて、出力先を /tmp/skill-loads.log など commit 対象外にする、という使い方も面白そうです。各自のマシンで自動的にログが溜まる仕組み。
自分の場合は、まず個人共通(~/.claude/settings.json)で動かしてみて、運用を見ながらリポジトリ内に展開するか考えていく予定です。
プロジェクトのskillsも対象、cwdで判別可能
hook は「Skill ツールが呼ばれたか」だけを見るので、skill の出所(user/project/plugin)を問わず記録されます。
ただ、ログだけでは出所が分からない。skill=foo としか出ないので、user 版と project 版のどちらが採用されたかは判別できません。
そこで cwd(カレントディレクトリ)をログに足すと、どのリポジトリから呼ばれたかは把握できます。完全な出所判別はできないけど、実用的にはこれで十分。プロジェクトごとにどの skill が使われているかが見えれば、棚卸しの判断材料としては足ります。
観測できるもの、できないもの
「どの skill が読まれたか」は観測できる(今回の hook で記録できた)。でも、「skill 本文のどの行が出力に影響したか」「どの規約を守って、どれを無視したか」は観測できない、という制約があります。
これは技術的というより原理的な制約です。LLM は確率的に出力するので、「この行を採用」「この行を無視」という決定論的な分岐が内部にない。観測する経路がない。
| 観測対象 | 可否 |
|---|---|
| skill が読み込まれた | ○(PreToolUse hook で記録) |
| ツール操作の結果(diff、コマンド) | ○(PostToolUse hook) |
| skill 本文のどの行が出力に影響したか | × |
| skill の規約に違反したか | △(近似のみ) |
「規約に違反したか」は近似で評価できます。Stop hook で別のモデルに「直前のターンで規約のどれを守り、どれを破ったか」を自己評価させる方法がある。ただ、これ自体がハルシネーション込みなので、信用しきれない。以前書いた「AIの自己評価を当てにしない」と同じ話です。
結局、規約を本気で守らせたいなら、lint やテストで機械的に強制するのが現実解です。これは、これまでの記事で繰り返してきた「指示ではなく仕組みで担保する」と整合します。
ここで気付くのは、AIに頼る限界です。skill に規約を書いても、AIが解釈して確率的に守る・守らない。守ったかの自己評価もAIに頼ると、それもまた確率的。AIで完結する検証ループには、原理的な限界があります。
参照ログの hook で分かるのは「呼ばれたかどうか」までで、「正しく機能したかどうか」までは届きません。それを知りたいなら、AIの外側で機械的に検証するしかない。
自分のskillsを見直してみた
ユーザーグローバル(~/.claude/skills/)に4つ:
github-actions: 1.2KB nuxt: 0.5KB rails: 8.9KB rspec: 29KB(50件超のフィードバック蓄積)
リポジトリ内(.claude/skills/)にも8つ:
github-actions: 1.2KB nuxt: 1.4KB rails: 0.7KB rspec: 17KB create-pr: 3.3KB git-commit: 4.2KB omit: 8.2KB update-pr: 1.9KB
並べてみて気付いたのは、同名の skill が user/project の両方にあって、しかもサイズが違うこと。例えば rspec は、ユーザーグローバルが 29KB、プロジェクトが 17KB。rails も、ユーザーグローバル 8.9KB に対して、プロジェクト 0.7KB と大きく違います。
理由は単純で、ユーザーグローバルは個人開発も含む複数プロジェクトをカバーするので、対応する範囲が広い。一方、プロジェクト内の skill は、そのプロジェクトに必要な内容だけで済む。スコープの違いが、サイズの違いに直結しています。
以前ハーネスについて書いた記事で書いた「設置場所は誰と共有したいかで決まる」が、自分の運用の中で実際に起きていました。同名重複は Claude Code の優先順位ルール(plugin > project > user)で片方だけ採用されるので、実効では8つの skill が動いている形です。
「分割した方がいいか」をAIに聞いたら、まず「今分けたい動機は何ですか?(context 節約 / 遵守率 / 編集しやすさ)」と聞き返されました。目的化させない配慮が、AIの応答にも入っているようで、ちょっと面白かったです。
結論としては、現状で困っていないなら分割は急がない、というのが妥当でした。29KB は確かに大きいけど、今の運用で困りごとが顕在化していないなら、整理(重複や古い内容の削除)を先にやるべき。分割は、整理してもまだ大きい場合の選択肢。
これも、以前書いた「最小から始めて、必要になったら追加する」と整合します。仕組みも分割も、目的化しないように気をつける必要があります。
他の選択肢の存在
skills の検証について調べる中で、Claude Code 固有の話ではないことに気付きました。
agentskills.io という共通仕様が業界に広がっていて、Claude Code、Gemini CLI、Cursor、Google ADK、その他 40以上の製品で同じ形式の skill が動くようになっています。「skills の参照ログを取りたい」という課題も、業界共通のようです。
Google ADK のようなマルチエージェントフレームワークでは、skill 関連のAPI(SkillToolset)が整理されていて、L1: 一覧、L2: 必要時に読み込み、L3: リソース、という progressive disclosure を体系化しているらしい。
ただ、これらは別レイヤーの道具です。ADK は「自分でAIエージェントを構築するフレームワーク」で、Claude Code のようなコーディングアシスタントの代替ではない。自分の使い方(コードを書くための支援)では、入れてすぐ得られるメリットはほぼない。
業界が動いているのを横目で見ながら、本当に必要になったら検討する。今は入れない判断も合理的だと思います。これは、以前書いた「全振りしない、延長線上で進める」の延長です。
バージョンアップ時の棚卸し
もう一つ気になっていた論点は、バージョンアップ時にどう対応するかでした。
これは、仕組みではなくプロンプトで完結する運用で十分そうです。
新モデルになったら、しばらく運用してみる。明らかにおかしい挙動や、古い skill が邪魔している兆候が出たら、AIに「これらの skills を新モデルで見直して。古い、不要、矛盾していたら指摘して」と依頼する。AIの指摘を、人間がレビューして判断する。
注意したいのは、AIに完全には任せないこと。AIは自分の限界を認識しにくいので、「これは不要」と言われても、人間が「最近使わなかったから不要」と「今後も使わないから不要」を区別する必要があります。特にガードレール系の skill は、AIが「もう不要」と判断しがちなので慎重に。
これは、以前書いた「判断と責任は人間が持つ」の応用です。仕組みを作らなくても、運用フローで対応できる。
まとめ
「skills を検証する仕組みが必要か」の答えは、規模次第かなと思います。
- 数個の skills: 目視で十分、仕組み不要
- 10-30個: ログがあると便利
- 30個以上: ログ必須、棚卸しの仕組みも検討
- 100個以上: 組織的な管理が必要
自分の規模(user/project 合わせて12ファイル、実効8個)では、まだ目視で追える範囲です。ただ、user 版と project 版で同名のものがあって、どっちが採用されているか即座には分からない。今回 hook を作ったのは、運用の中で気になった論点を確かめるためと、cwd を見ながら設置場所の判断材料にするためで、検証が目的化しないように気をつけたいところです。
そして、観測できることには原理的な限界があります。「呼ばれたか」は記録できるけど、「どの行が効いたか」「規約を守ったか」は観測できない。本気で守らせたい規約は、lint やテストで機械的に強制する。これは、これまで繰り返してきた「指示ではなく仕組みで担保する」の話と同じです。
業界では、Google ADK のような選択肢もあるし、agentskills.io のような共通仕様も整いつつある。でも、AIコーディングでは今の所、メリットがないので、入れない判断も合理的です。「全振りしない、延長線上で進める」「目的化させない」という、これまでの記事で繰り返してきた立場の延長です。
これも結局、いつものエンジニアリングの延長な気がしています。最小から始めて、運用で育てる。仕組みを作る前に、運用で解決できないか考える。観測できないものに頼らない。AIコーディング特有の話というより、何かを設計するときの基本かもしれません。
