はじめに

Claude Code Skillsにハマりました。

最初は1つ、2つ。定型作業を自動化するだけのつもりでした。自作のSkillが半年で20個を超え、さらにsuperpowersやeverything-claude-code等のプラグインを入れた結果、気づけば50個以上のSkillを運用する環境になっていました。

最初は確かに便利でした。「これ、全部Skillにすればいいじゃん」と思っていた時期もあります。しかし30個を超えたあたりから、明らかに様子がおかしくなりました。Skillを使いこなしているはずなのに、作業がスムーズに進まない。何かがおかしいと感じ始めました。

この記事では、Skillsを50個以上運用して実際に起きた問題を整理します。解決策は次回のPart 2に譲り、本記事では「問題提起」に集中します。

本記事はAgent Skillsの基本を理解している方を対象にしています。Skillsの概要や作成方法は「Claude Code Skills 完全活用ガイド 2026」を参照してください。

Skillsが増えるとなぜ問題になるのか

理論の話ではありません。自分が実際に体験した話です。

「どのSkillを使えばいいか分からない」問題

50個もあると、似た目的のSkillが複数存在し始めます。

自分の環境では、トレンド関連だけで3つのSkillがあります。fetch-trends（単発のトレンド収集）、aggregate-trends（8チャンネル並列収集）、daily-topic-ideas（記事ネタ向けのトレンド収集）。それぞれ微妙に用途が違いますが、「最近のAI動向を知りたい」というざっくりした目的のとき、どれを使えばいいか一瞬迷います。

問題は迷う時間の長さではありません。似たSkillが複数あると、「この場面ではどちらが適切か」の判断自体が難しくなります。各Skillの細かな違いを正確に覚えていないと、正しい選択ができません。結果として、fetch-trendsで十分な場面でaggregate-trendsを実行してしまい、8チャンネル並列で走るため完了まで数分待つことになります。Skillの管理が甘いと、こうしたミスが日常的に起きます。

トリガーワードの競合

CLAUDE.mdにトリガーワードを定義していますが、ワードが似ているSkillは意図しない方が発火します。

「トレンドは？」と聞くと、fetch-trendsが動いてほしい場面でaggregate-trendsが起動することがありました。両方のdescriptionに「トレンド」が含まれているため、Claude側の判断が安定しません。結果として、毎回「/fetch-trendsを実行して」とスラッシュコマンドで明示的に指定するようになりました。

自然言語で呼び出せるのがSkillsの魅力だったはずです。しかしSkillが増えるほど、曖昧な指示では正しいSkillが選ばれなくなります。自然言語の利便性が、Skillの数に反比例して失われていきます。これは想定外でした。

Skillの存在を自分が忘れる

笑い話のようですが、本当にあった話です。

ある日、「記事のタイトル案を5パターン出して」と手動で指示を出しました。いつも通りClaudeが考えてくれて、まあまあの結果が返ってきました。翌日、CLAUDE.mdを整理していて気づきました。generate-titlesというSkillがあることに気づきました。タイトル生成に特化したプロンプトと出力フォーマットが定義されていて、手動で指示するよりずっと良い結果が出るSkillです。自分で作ったにもかかわらず、完全に忘れていました。

50個もあると、すべてを把握し続けるのは無理です。特に月に1回しか使わないSkillは、存在自体を忘れます。作ったことすら覚えていないSkillが出てくるのは、さすがに管理が破綻しているサインでした。

サードパーティ製Skillとの混在

問題をさらに複雑にしているのが、自作以外のSkillの存在です。

superpowersやeverything-claude-codeといったプラグインをインストールすると、数十個のSkillが一気に追加されます。マーケットプレイス経由でインストールしたSkillも加わります。自分の環境では、自作とプラグイン経由を合わせて50個以上のSkillが読み込まれています。

こうなると、「このSkillは自分が作ったものか、プラグインで入ったものか」が分からなくなります。似た名前のSkillが自作とサードパーティで重複していることもあります。draft-articleという自作Skillと、プラグインが提供するarticle-writingが共存していて、どちらが発火するか予測できない状態になったこともありました。

.claude/skills/の中身をlsしてみると、見覚えのないSkillが大量にあります。どのプラグインが追加したものか、まだ必要なのか、自作のSkillと競合していないか。これを把握するだけでも一苦労です。

名前規約（自作Skillにプレフィックスをつける等）で整理する手もありますが、後付けで全Skillをリネームするのは影響範囲が大きく、簡単にはいきません。この問題の対処はPart 2で扱います。

増やすほど生産性が下がるパラドックス

Skillの数と生産性の関係を、自分の体感で振り返ります。

Skill 1〜10個: 生産性2倍の体感

最初の10個は劇的でした。朝の工程表作成（morning-planner）、トレンド収集（fetch-trends）、記事の下書き（draft-article）、メモリ保存（save-memo）、Issue登録（auto-issue）。どれも週に何度も繰り返す作業で、Skill化の効果がすぐに実感できました。

定型作業が一発で終わる。出力フォーマットも安定する。「もっと作ろう」と自然に思いました。

Skill 11〜20個: まだ快適

ワークフローの大部分をカバーできた時期です。経理更新、週次レポート、タイトル生成、記事執筆パイプライン、戦略分析。業務のほぼ全領域にSkillが行き渡りました。

この段階ではまだ全Skillを把握できていました。「この作業はこのSkill」という対応が頭に入っていて、迷いもありませんでした。

Skill 21〜30個+プラグイン導入: 管理の手間が見え始める

自作Skillが20個を超えたあたりで、superpowersやeverything-claude-code等のプラグインも導入しました。一気に数十個のSkillが追加され、環境内のSkill総数が30個を超えます。ここから雲行きが変わりました。

まず、Skillの更新忘れが発生しました。MCPサーバーのツール名が変わったのに、それを参照しているSkillを更新していませんでした。エラーが出て初めて気づきます。

次に、似たSkillの乱立が始まりました。自作のSkillとプラグインが提供するSkillで用途が被るケースも出てきます。「この用途のSkillはなかったっけ？」と探すのが面倒で、つい新しく作ってしまいます。結果として、目的が重複するSkillが生まれます。

CLAUDE.mdのトリガーワード定義も肥大化しました。テーブルが長くなり、一覧性が落ちます。新しいSkillを追加するたびに、既存のトリガーワードと競合しないか確認する手間が増えました。

Skill 30〜50個: メンテコストが生産性を食い始める

この段階で、生産性の向上カーブが明らかに鈍化しました。

新しいSkillを1つ追加するたびに、以下の作業が発生します。

CLAUDE.mdのトリガーワードテーブルに追記
既存Skillとの競合チェック
依存するMCPサーバーやAPIの動作確認
数週間後の「まだ正しく動いているか」の確認

30個を超えたあたりからは、利用頻度が月1〜2回のニッチなものが多いです。使用頻度が低いSkillほど、壊れていても気づきにくいです。気づいたときには「いつから壊れていたのか」すら分かりません。

体感としては、最初の10個で得た生産性向上の3割くらいを、残り40個のメンテナンスコストで吐き出している感覚です。

これは「Skillsを10個以内に抑えるべき」という話ではありません。問題はSkillの数ではなく、管理の仕組みがないことです。コードが100ファイルあっても、テストとCIがあれば管理できます。Skillsにはそれがないのが根本原因です。

実際に起きた5つのトラブル

ここからは具体的なトラブル事例です。

トラブル1: MCPサーバーの仕様変更で静かに壊れた

Google Workspace系のMCPサーバーがアップデートされ、ツール名が変わりました。google_sheets_readがgoogle_sheets_get_valuesに変更されたのです。

sync-accountingスキルはこのツールに依存していました。しかし、エラーメッセージはTool not foundと出るだけで、Skill全体がクラッシュするわけではありません。Claudeは「ツールが見つからなかったので、代替手段で対応します」と、別のアプローチで処理を試みます。

結果、微妙に違うデータが返ってきました。正しいデータに見えますが、取得元のシートが違っていました。気づいたのは2週間後、月次の経理チェックのときです。

この「静かに壊れる」パターンが一番怖いです。エラーで止まってくれるなら気づけます。それっぽい結果を返してくるから見逃します。

トラブル2: Claude Codeのアップデートでhooksが変わった

Claude Code本体のアップデートで、PreToolUse/PostToolUse Hookが渡すfile_pathの形式が変わりました。相対パスが渡されるケースがあった仕様が、絶対パスに統一されました。

自分のHookスクリプトでは、file_pathの先頭が./で始まる前提でパス判定をしていました。絶対パスに変わった結果、条件分岐が常にfalseになり、Hookが何もしなくなりました。

エラーは出ません。ログにも異常はありません。Hookは正常に発火しているけれど、処理がスキップされているだけです。気づいたのは3日後でした。出力ファイルが生成されていないことに違和感を覚え、半日かけて原因を特定しました。

トラブル3: 同じ目的のSkillを2つ作っていた

これは純粋に自分の管理不足です。

記事の下書きを生成するSkillとしてdraft-articleがありました。ある日、「もっとリサーチを深くしてから書くSkillが欲しい」と思い、research-deepを作りました。さらに後日、「記事のネタ出しからやってくれるSkillが欲しい」と思い、idea-generatorを作りました。

ここまでは意図的です。問題は、数ヶ月後にdraft-articleの中身を見返したとき、リサーチ工程を含むように拡張されていたことです。過去の自分がいつの間にか機能を追加していました。結果としてdraft-articleとresearch-deep + draft-articleの組み合わせが、ほぼ同じことをする状態になっていました。

Skillが5個なら全体を把握できます。50個になると、各Skillの現在の状態を正確に把握するのは困難です。

トラブル4: チームメンバーがSkillの出力を無検証で使った

自分が作ったSkillを、プロジェクトのメンバーにも共有していました。aggregate-trendsは8チャンネルからトレンドを並列収集するSkillで、毎朝の情報収集に重宝していました。

あるとき、メンバーがaggregate-trendsの出力をそのままクライアント向け資料に転記しました。しかしそのとき、8チャンネルのうち2つがAPIの認証エラーで取得に失敗していました。Skillの出力には6チャンネル分のデータしか含まれていませんでしたが、出力フォーマット上はそれが分かりにくい構造でした。

「Skillが出した結果だから正しいだろう」という信頼が裏目に出たケースです。Skillの出力は「AIが生成したもの」であり、常に検証が必要です。しかし、Skillが安定して動いている期間が長いほど、検証を怠りがちになります。

トラブル5: メンテナンスに週2時間以上かかるようになった

50個のSkillを維持するために、以下の作業が定期的に発生します。

Claude Codeアップデート後の動作確認（月2〜3回）
MCPサーバーの更新チェック（月1回）
CLAUDE.mdのトリガーワード整理（月1回）
壊れたSkillの修正（不定期、月2〜3件）
Skillの出力品質チェック（週1回）

積み上げると、週あたり2時間以上です。Skillsで節約している時間が週3〜4時間だとすると、純粋な効果は半減しています。しかもメンテナンス作業自体が退屈で、後回しにしがちです。後回しにすると壊れたSkillが放置され、次に使ったときにトラブルが起きる。悪循環です。

なぜこうなるのか — Skillsの構造的な特性

個別のトラブルを見てきましたが、根本には構造的な原因があります。

Skillsはコードではなくプロンプト

Skillsの実体はMarkdownファイルです。プログラミング言語のコードではありません。そのため、通常のコードのようなユニットテストを書くのが困難です。

コードならassertで期待値を検証できます。Skillsの場合、「期待通りの出力か」の判定自体が曖昧です。LLMの出力は非決定的で、同じ入力でも毎回少しずつ違う結果が返ります。「壊れた」と「出力のバリエーション」の境界が不明瞭です。

依存関係が暗黙的

Skillは内部でMCPサーバーのツールを呼んだり、外部APIにアクセスしたり、他のSkillを参照したりします。しかし、これらの依存関係はSkillのMarkdown内に自然言語で書かれているだけです。

## 手順
1. google_sheets_get_values で経理データを取得
2. 取得したデータを整形
3. output/finance/ に保存

コードならimport文やpackage.jsonで依存関係が明示されます。Skillsにはそれがありません。どのSkillがどのMCPサーバーに依存しているかを把握するには、標準的な方法では一覧化されないため、手動での確認に頼りがちです。

バージョン管理はできるが、検証が難しい

SkillsのファイルはGitで管理できます。変更履歴も追えます。しかし「この変更でSkillが壊れていないか」を自動で検証するファーストクラスの仕組みがまだ整っていません。

コードならgit pushのたびにCIが走り、テストが通るか確認できます。Skillsにはその仕組みがないため、「変更後に手動で動かして確認する」しかありません。50個のSkillを毎回手動確認するのは現実的ではなく、結果として確認を省略しがちになります。

コンテキストの圧迫

Claude Codeのコンテキストは1Mトークンまで拡張され、容量自体が問題になることは少なくなりました。とはいえ、Skill自体がコンテキストを消費する事実は変わりません。

Agent Skills仕様のProgressive Disclosure設計により、セッション開始時には各Skillのnameとdescriptionだけが読み込まれます。1つあたり50〜100トークン程度で、70個あっても数千トークンです。1Mの中では微々たるものです。

ただし、タスクに合致したSkillが選ばれるとSKILL.mdの本文全体が読み込まれます。複数のSkillが同時に選択されることもあります。容量としては余裕があっても、Skillの数が多いとLLMの注意（Attention）が分散しやすくなります。無関係なSkillの情報がコンテキストに混ざることで、指示の理解精度が微妙に落ちる可能性があります。

致命的な問題ではありませんが、「不要なSkillは整理しておくに越したことはない」という意識は持っておくべきです。

「正しく動いている」の定義が曖昧

これが最も根深い問題です。

コードのテストでは、入力と期待出力を定義して一致を確認します。Skillsの場合、同じ入力に対して毎回異なる出力が返ります。「トレンドを収集して」の結果は、実行日によって当然変わります。

では何をもって「正しい」とするのか。出力フォーマットが崩れていないこと？必要なセクションが含まれていること？情報源が正しいこと？これらを定義し、自動で検証する仕組みが必要ですが、現時点では標準的な手段が確立されていません。

まとめ — 問題は「Skillsが悪い」ではなく「管理の仕組みがない」

誤解のないように書いておきます。Skillsは間違いなく強力です。自分の業務効率は、Skills導入前と比べて確実に向上しています。

問題は、Skillsの数が増えたときの管理手法が確立されていないことです。

コードには長い歴史の中で培われた管理の仕組みがあります。ユニットテスト、CI/CD、コードレビュー、リンター、依存関係管理。これらがあるから、数百ファイルのプロジェクトでも品質を保てます。

Skillsにはまだそれがありません。Git管理はできますが、テスト・CI・リンターといった仕組みが標準では用意されていません。結果として、Skillの品質は「作った人の記憶力と勤勉さ」に依存します。5個なら記憶力で回せます。50個になると破綻します。

次回のPart 2では、この問題に対する具体的な解決策を共有します。SkillsにCI/テスト/品質管理の仕組みを導入し、50個以上のSkillを安定運用するための設計です。

本記事で挙げた問題に心当たりがある方は、ぜひコメントで「うちではこう対処している」を教えてください。Skillsの管理手法は、コミュニティ全体で知見を共有していくべきフェーズにあると感じています。