Skills の陳腐化は避けられない──検知・回復・局所化の運用設計¶

対象 / ポイント

対象: AI コーディングエージェントの Skills・custom instructions・prompt files を実務で運用しており、「作ったSkillがいつの間にか効かなくなっている」問題に心当たりがある開発者・チームリード。

ポイント:

Skills の陳腐化は 5 つの異なるメカニズムで起き、原因ごとに対策が違う
「良い書き方」より「評価ループ」を回すほうが陳腐化への耐性が高い
SKILL.md 本体には固定コアだけ置き、可変情報を外へ逃がす 3 層分離が基本設計になる

結論：陳腐化は避ける対象ではなく、運用で制御する対象¶

Skills は書いた瞬間から古くなり始める。モデルが賢くなり、API が変わり、チームのワークフローが変わる。この前提に立つと、目指すべきは「古くならない Skill」ではなく「古くなっても壊れにくい運用」になる。

Anthropic の skill-creator 更新（2026年3月）、OpenAI の eval 運用ガイド、GitHub Copilot のカスタマイズ階層、LangChain の Skill 評価レポートなど、主要プレイヤーの直近ドキュメントはいずれもこの方向に収束している。検知しやすく、直しやすく、影響範囲を小さくする──これが Skills 運用の正攻法だ。

なぜ Skills は古くなるのか──5 つの陳腐化パターン¶

このセクションが答える問い：「Skill が効かなくなった」とき、原因はどこにあるのか。

「Skills が古くなる」を一括りにすると対策がぼやける。実務で起きる陳腐化は、少なくとも 5 つの異なるメカニズムに分かれる。

1. トリガー陳腐化¶

description や名称が、ユーザーの実際の依頼文と合わなくなる状態。Skill 本体がどれだけ正しくても、発火しなければ存在しないのと同じだ。

コミュニティ検証では、description の具体化と例の追加によって発火率が大きく改善したという報告がある¹。検証条件は著者依存だが、description が曖昧なまま放置された Skill が実質的に死んでいるという現象は十分に起こりうる。

Anthropic も description には「何をするか」と「いつ使うか」の両方を書くことを求めており、Use when ... 構文で具体的なユーザー表現を入れた例を推奨している²。

2. 手順陳腐化¶

Skill 本文に書いたワークフローが、現実のツールや運用とズレる状態。たとえば API の v1 → v2 移行、CLI オプションの変更、レビュープロセスの改定などで起きる。

Anthropic のベストプラクティスでは、旧パターンを HTML の <details> タグで折りたたんで保持する手法が示されている³。「以前のやり方」が存在すること自体を SKILL.md の設計に織り込んでいるわけだ。

3. コンテキスト劣化¶

Skill が長くなりすぎ、モデルの recall が落ちる、あるいはメタデータ予算を圧迫して他の Skill が除外される状態。

Skill が効かない原因は SKILL.md 本体の長さだけではない。Claude Code では、利用可能な Skills の説明メタデータにも文字数予算がある。公式 docs では「context window の 2%、fallback 16,000 characters」とされており、多すぎると一部 Skill が除外される⁴。/context で除外警告を確認しつつ、description の簡潔さと SKILL.md 本体の分割を両方見る必要がある。SKILL.md 本体については、公式の推奨は 500 lines 未満だ³。なお、予算を超えた場合に SLASH_COMMAND_TOOL_CHAR_BUDGET 環境変数で上限をオーバーライドすることも可能だ⁴。

エラーも警告も出ないケースがある点が厄介で、EvalView はこうした構造上のバリデーション（バジェット超過、セクション不足の検出）を自動化している⁵。

4. プラットフォーム陳腐化¶

モデル更新、API 移行、機能のプレビュー解除や終了で、Skill 側を変えていないのに動作が変わる状態。

Claude Code の直近リリースでは、skill hooks の二重発火修正や、--resume ごとの skill listing 再注入の修正（約 600 トークン節約）が入っている⁶。Skill の文面は一切変えていなくても、プラットフォーム側の挙動変化で結果が変わる実例だ。OpenAI も Assistants API を deprecated とし 2026年8月に shutdown 予定で Responses API への移行を案内しており、こうした基盤移行は定期的に起きる。

5. 組織知の陳腐化¶

チームで使われる言い回し、レビュー観点、禁止事項、ディレクトリ構成が変わるのに Skill が追随しない状態。Skill が「書かれた当時のチーム」に最適化されたまま固定される。

40 件以上の Skill 失敗を分析したレポートでは、コミュニティの 3 大ペインポイントとして「期待通り発火しない」「出力に大幅な手修正が必要」「Claude が見当違いの処理をする」が挙がっている⁷。これらの多くは、Skill が書かれた時点のワークフロー前提と現在との乖離が根因だった。

たとえば、セキュリティレビュー Skill を考える。作成時点のレビュー基準は正しく発火し、正しく動作する。しかし半年後、チームがサプライチェーン攻撃への対応を基準に追加しても、Skill 側は更新されない。結果として「レビューは毎回通っているが、新しい観点だけが抜け続ける」状態になる。Skill は壊れていない。ただ、組織の知識に追いついていないだけだ。

診断マップ：症状から原因を特定する¶

5 パターンを頭に置いたまま次のセクションを読むのは負荷が高いので、実務で使える対応表を先に整理する。

症状	主要原因	最初の対処
発火しない	トリガー陳腐化	description と実際の依頼文のズレを確認する
出力が古い手順を踏む	手順陳腐化	可変情報を REFERENCE.md へ逃がす
Skill があるのに効きが弱い	コンテキスト劣化	本体を削る・分割する。`/context` で予算確認
昨日まで動いたのに今日おかしい	プラットフォーム陳腐化	release notes / deprecations を確認する
チーム実態と噛み合わない	組織知の陳腐化	実運用で外れたケースを eval に戻す

以降のセクションでは、この 5 パターンへの対策を設計・ツール・運用の順に展開する。

なお、この 5 分類は 「どこが壊れたか」（故障モード） の分類であり、次に触れる Anthropic 公式の 2 分類は 「Skill がどんな役割か」 の分類だ。両者は直交しており、組み合わせて使うと診断精度が上がる。

Capability Uplift と Encoded Preference──Anthropic 公式の 2 分類との接続¶

このセクションが答える問い：Skill の役割によって、注意すべき陳腐化パターンは変わるのか。

Anthropic は Skills を大きく 2 つに分類している⁸。

Capability Uplift Skill は、ベースモデルが単独ではできないこと、または安定してできないことを補う Skill だ。ドキュメント生成系がその代表で、プロンプトだけでは再現しにくいパターンをエンコードしている。これらは主に 手順陳腐化 と プラットフォーム陳腐化 の影響を受ける。モデルが進化して Skill なしでも eval を通過するようになった場合、その Skill は「間違い」ではなく「不要」になったということだ⁸。

Encoded Preference Skill は、モデルが既にできることを、チーム固有のプロセスに沿って実行させる Skill だ。NDA レビュー手順や週次レポート生成がその例になる。これらは主に トリガー陳腐化 と 組織知の陳腐化 の影響を受ける。Skill 自体は正しく動作しているが、参照先のワークフローが変わったために「正確に間違った結果」を出す。

この対応関係を意識すると、Skill の種類に応じて重点的に監視すべき陳腐化パターンが決まる。

Skill 化は常に改善なのか¶

このセクションが答える問い：とりあえず Skill にすればよくなるのか。

evaluation-first の原則から見ると、Skill の追加は「改善策」ではなく「仮説」だ。仮説には検証が必要になる。

Anthropic のベストプラクティスは、Skill を書く前にまず Skill なしで代表的なタスクを実行し、具体的な失敗や不足を文書化してから、最小限の命令を書くプロセスを推奨している³。これは evaluation-first の思想であり、baseline を取らないまま Skill を足すと「改善したかどうか」が判定できない。

コミュニティ側でも、公開 Skill を大量に導入したところ、多くのケースでバニラ状態の出力より結果が悪化したという検証報告がある⁹。著者の評価条件に依存するため一般法則として扱うべきではないが、「Skill 化すれば自動的に良くなる」という前提が危うい、という指摘としては有用だ。トークン追加によるレイテンシ増加、出力を狭める制約の注入が逆効果になるパターンは、十分にありうる現場症状だろう。

ここから導かれるのは、Skill にすべき対象の選定が運用設計の入口になるということだ。何でも Skill に入れるのではなく、Skill なしの baseline と比較して明確な改善がある場合にだけ Skill 化する。

設計原則：固定コア / 可変詳細 / 実行時参照の 3 層分離¶

このセクションが答える問い：SKILL.md の中身をどう構成すれば陳腐化に耐えるか。

陳腐化に強い Skill は、変更頻度の異なる情報を同じ場所に置かない。以下の 3 層に分けると安定する。

固定コア（SKILL.md 本体） には「役割」「原則」「安全制約」「高レベル手順」だけを置く。Skills の progressive disclosure 設計では、frontmatter（メタデータ）は常時見えるが、SKILL.md 本文は relevant と判断されたときに読み込まれ、linked files は必要時にだけ読み込まれる¹⁰。公式の推奨は SKILL.md 本体 500 lines 未満³。この枠内に収まるよう、本体は概要に留める。

可変詳細（REFERENCE.md・別ファイル） には「API 仕様」「CLI オプション」「社内運用手順」「例外ケース」を置く。Anthropic は SKILL.md を短く保ち、追加ファイルを必要時読み込みにすること、さらに参照は深くネストせず SKILL.md から 1 段で辿れるようにすることを勧めている³。

実行時参照（外部ドキュメント・検索対象） には「頻繁に変わるドキュメント」「ベンダー固有の設定値」「チーム wiki」を置く。Tool Search Tool や defer_loading で必要なツールだけを後から読み込む設計も、この層の実装パターンだ。

Anthropic のベストプラクティスのチェックリストには "No time-sensitive information (or in old patterns section)" が含まれている³。時間に弱い情報を SKILL.md 本体に置かないことが、陳腐化対策で一番効くベストプラクティスだ。

因果シーケンス：手順陳腐化が起きるとき¶

手順陳腐化が検知なしに進行する典型パターンを追ってみる。

ベンダーが API v2 をリリース → SKILL.md は v1 のエンドポイントを参照したまま → Skill は正常に発火する → 生成されたコードが v1 を呼ぶ → テストは通る（v1 がまだ動いている）→ 数か月後に v1 が shutdown → 初めてエラーになる → 原因調査で Skill の記述に到達

この連鎖で問題なのは、shutdown まで検知できない点だ。3 層分離で API エンドポイントを可変詳細に逃がしておけば、ベンダー changelog 確認時に更新対象を特定しやすい。SKILL.md 本体を grep する必要がなくなる。

評価ループ：3 系統のテストで陳腐化を検知する¶

このセクションが答える問い：Skill の劣化をどうやって見つけるか。

陳腐化対策の中心は「よい書き方」ではなく評価ループだ。テストは 3 系統に分けると抜け漏れが減る。

Positive trigger は「この依頼で発火してほしい」テスト。明示的な依頼文だけでなく、言い換えや間接的な表現も含める。Anthropic の公式ガイドでは obvious（明示的）/ paraphrased（言い換え）/ unrelated（無関係）の 3 類型が示されており、10-20 のテストクエリで発火率を測定することが推奨されている¹³。

Negative trigger は「この依頼では発火してほしくない」テスト。Skill 数が増えるほど false positive（誤発火）のリスクが上がる。LinkedIn 投稿 Skill が YouTube スクリプト依頼で発火する、といった事例が報告されている¹¹。

Behavioral correctness は「発火後の出力が正しいか」テスト。AutoResearch Eval Loop では、20-30 ケース × 3-6 個の binary yes/no テストで構成し、failure mode ごとにテストを追加していく運用が提案されている¹²。

最小の eval セット構成例¶

prompt,expected_trigger,type,check
"売上CSVを分析して",true,positive,"KPI分解が含まれるか"
"このデータからレポートを作って",true,paraphrased,"グラフが生成されるか"
"Pythonのfor文を教えて",false,unrelated,"-"
"会議の議事録を要約して",false,boundary,"-"

10-20 件から始め、実際に起きた失敗を都度追加する。完全な eval セットを最初から作ろうとしない。

週次で見るべき観測信号

eval を回すだけでは不十分だ。本番の動きから陳腐化の兆候を拾う観測ポイントがある。

発火率の低下 ── 以前拾えていた依頼を取りこぼし始めたら、トリガー陳腐化の兆候
False positive の増加 ── 意図しない場面で発火するなら、description の境界が曖昧になっている
Skill あり/なしの差分縮小 ── モデルの基本能力が追いついた可能性。Capability Uplift Skill で特に注意
失敗ケースの再発 ── 一度潰した失敗が戻ったら、プラットフォーム陳腐化（モデル更新）を疑う
Vendor release notes に Skill 関連の変更 ── Skill 側の問題に見えて基盤変更が原因のケース

全部を毎週見る必要はない。直近で変更が入った領域に絞り、該当があれば eval を再実行する。

2026年3月の skill-creator 更新と周辺ツール¶

このセクションが答える問い：具体的にどのツールで何をするか。

作成と改善¶

Anthropic の skill-creator は 2026年3月の更新で、eval の作成・実行、ベンチマーク（pass rate / 実行時間 / トークン消費の記録）、A/B 比較（ブラインド評価）、description の最適化に対応した⁸。Anthropic 自社の document-creation skills で 6 つ中 5 つの発火精度が改善された実績がある⁸。

注目すべきは multi-agent 対応で、独立したエージェントが並列で eval を実行し、コンテキストの混入を防ぐ設計になっている⁸。eval を直列で回すと前のテストの文脈が次に漏れる問題があったが、これで解消される。

回帰検知の自動化¶

Promptfoo は CLI ベースの test-driven prompt engineering ツールで、Skill 変更時に CI で eval を回す用途に向く。PromptLayer は新しい prompt version ごとに evaluation pipeline を自動実行する CI を提供している。

バージョン管理と本番観測¶

LangSmith は prompt の commit tags と dataset のバージョン化を持ち、特定バージョンに prod タグを付けて評価できる。Phoenix は OTLP ベースで model calls / retrieval / tool use を trace できる。机上の良い Skill でも、本番で「どこで外したか」を見ないと陳腐化は検知できない。

構造バリデーション¶

EvalView は SKILL.md の構造バリデーション（バジェット超過、セクション不足の検出）と振る舞いテストを提供する⁵。API キー不要で deterministic に動くため、CI の最初のゲートとして使える。

器の使い分け──全部を Skill に入れない¶

このセクションが答える問い：Skill 以外の選択肢はあるのか。

GitHub Copilot の整理が参考になる。broad standards（全体に効くルール）は custom instructions、単発再利用は prompt files、複数資産を束ねる多段ワークフローは agent skills、絶対実行ルールは hooks。変更頻度の異なるものを同じ器に入れると、一方の更新がもう一方を巻き込んで一気に陳腐化する。

Claude Code でも同様の階層がある。常時読み込まれる CLAUDE.md、プロジェクト固有の .claude/ 設定、必要時ロードの Skills、イベント駆動の hooks¹⁴。CLAUDE.md は常にロードされ trigger 信頼性の問題がない分、変更頻度が低い安定ルールの置き場として優れている。

判断基準はシンプルだ。そのルールは「毎回必要か、特定タスクでだけ必要か」「変更頻度は月単位か、週単位か」。この 2 軸で器を選ぶ。

最小運用フェーズ¶

このセクションが答える問い：明日から何をすればいいか。

Phase 1 ── SKILL.md を「役割・適用条件・高レベル手順」に縮める。API 名、CLI フラグ、UI 手順などの可変情報は REFERENCE.md へ退避する。

Phase 2 ── positive / negative / correctness の 10-20 ケースで小さな回帰セットを作る。完璧を目指さず、現時点で思いつく代表ケースだけでよい。

Phase 3 ── Skill 変更時に eval を回す。CI に組み込めるならベストだが、手動実行でも「変更前後で結果が変わったか」を見るだけで十分に機能する。

Phase 4 ── 本番で Skill が外したケースを週次で 1 件ずつ回帰セットへ追加する。テストセットは最初から完成させるものではなく、失敗から育てるものだ。

Phase 5 ── 月次でベンダー changelog / deprecation を棚卸しする。Anthropic の model deprecations、Claude Code release notes、利用している外部 API の変更履歴が対象になる。

まとめ¶

Skills の陳腐化は単一の問題ではない。トリガー、手順、コンテキスト、プラットフォーム、組織知の 5 つの異なるメカニズムで起き、それぞれ対策が違う。

「古くならない Skill を書く」ではなく「古くなっても壊れにくい運用を作る」に発想を転換すると、やるべきことが明確になる。SKILL.md 本体には固定コアだけ置く。評価ループを回す。失敗をテストセットへ追加する。ベンダー変更を月次で確認する。

2026年3月の skill-creator 更新で入った eval / benchmark / A/B 比較 / description 最適化は、この運用を支える基盤として設計されている。「Skill を作る」フェーズから「Skill を保守する」フェーズへの移行が、2026年前半の実務上のテーマになるだろう。