チームのClaude Codeスキルが増えすぎたときに見直したい、整理の基本
はじめに
先日の勉強会で、「メンバーがそれぞれ独自のスキルをたくさん作っていて、収拾がつかなくなっている」という話を聞きました。
Claude Codeのスキルは、手順をMarkdownに書いて置くだけで作れます。 手軽に作れるぶん、気付いたら似たようなスキルが何個も並んでいた、ということが起きやすい仕組みです。 生成AIを使った開発のやり方は数か月単位で変わっており、各自が手探りで工夫した結果としてスキルが増えるのは無理もありません。
ただ、誰かが一人で片付けても、置き方のルールがなければ半年後にはまた元どおりになります。 片付けに加えて、「何をどこに置くか」と「増えすぎないための仕組み」を決める必要があります。
この記事では、複数人で開発しているリポジトリでスキルが乱立したときの基礎的な対応方法を紹介します。 記事は長めなので、何から始めるかだけを知りたい場合は、後半の「まず着手するなら、この3つ」から読んでください。
スキルの乱立を止めて、整理された状態を保つ方法
乱立は個人の問題ではなく、仕組みの問題
スキルが乱立すると、次のような困りごとが起きます。
似た指示が複数あり、内容が矛盾していても気付けない
常に読み込まれる設定が増えて、Claudeの作業スペース（コンテキスト）を無駄に使う
どのスキルを使えばよいか分からず、結局また新しいスキルが作られる
これは、作った人が悪いわけではありません。 乱立は、次のものが欠けているときに起きます。 以降の節は、この順に対応策を説明します。
個人の試作と、チームで共有するものの境界（置き場所）
何をスキルにすべきか、1つをどの大きさにするかの基準
スキルの作り方の基準
共有される前に止める仕組み
判断して整理する人
置き場所：個人用と共有を分ける
Claude Codeのスキルには、大きく2つの置き場所があります。
個人用：~/.claude/skills/
自分のPCのホームフォルダにあり、リポジトリには含まれないので、他のメンバーには影響しません
共有：リポジトリ内の .claude/skills/
Gitでコミットされ、マージされた時点で全員に配られます
ここでいう「個人用」は、Gitのブランチのことではありません。 作業ブランチの .claude/skills/ にコミットしたスキルも、マージされれば全員に届くので、どのブランチでも「共有領域への変更」として扱います。
そのうえで、流れを次のように決めておきます。
個人用（~/.claude/skills/）で試作 → 有用ならPRで共有へ昇格 → レビュー → マージ作ること自体は止めずに、共有までの道筋を一本にするのがポイントです。
スキルにすべきか：4つの仕組みを使い分ける
スキルが増えすぎる背景には、本来スキル以外で扱うべき内容までスキルとして作られていることがよくあります。 Claude Codeには、スキルを含めて4種類の仕組みがあります。
Rules（CLAUDE.md や .claude/rules/）：常に守る前提や規約。毎回自動で読み込まれます（paths を指定したRulesは、対象のファイルを扱うときだけ）
Skills（.claude/skills/）：特定の作業の手順。必要なときだけ読み込まれます
Agents（.claude/agents/）：独立した文脈で作業を任せる専門の担当です
Hooks（.claude/settings.json など）：ファイル編集の前後などの決まったタイミングで、必ず実行される処理です
どれにするか迷ったら、次の順に問いかけます。
必ず守らせたいか？ → Hooks、または settings.json の許可設定（permissions）
常に意識させたいか？ → Rules
特定の作業で手順が必要か？ → Skills
メインの会話を汚さずに丸ごと任せたいか？ → Agents
たとえば「コミット前に必ずlintを通す」をスキルに書いても、Claudeがスキルを読まなければ守られません。 スキルの中身はClaudeへのお願いなので、効くかどうかは確率的です。 一方でHooksは、有効になっている限りClaude Code側がスクリプトを実行するので、毎回同じように動きます。
1つの大きさをそろえる
1つの大きさが人によってばらつくと、大きなスキルの一部と小さなスキルが重なって重複が生まれます。 そこで、4種類それぞれについて「1つ」をどの単位で切るかを決めておきます。
Rules：1つの関心領域（どの範囲に適用するか）
1ファイル1テーマで、数十〜100行程度が目安です。良い例は rules/api.md、悪い例は何でも入った rules/all.md です
Skills：1つの作業（何をするか）
「マイグレーションを追加して」のように頼める単位で、名前を動詞で言えることが目安です
良い例：db-migration-add、release-notes-create
大きすぎる例：backend-development（いつ使うのか曖昧）。小さすぎる例：format-date（Rulesかコードの関数で十分）
Agents：1つの役割（誰として動くか）
同じ観点で判断し、同じツール権限で済む範囲が1つです。良い例は、読み取り専用でレビューする code-reviewer です
作るのは、「文脈を分けたい」「権限を絞りたい」「観点を固定したい」のどれかに当てはまるときだけです。5個前後から始めます
Hooks：1つのチェックや自動処理（いつ何を保証するか）
1つのイベントで1つの目的に絞り、数秒で終わる処理にします。詰め込むと、どこで失敗したのか分からなくなります
大きさや種類の選び方がずれてくると、次のようなサインが出ます。
スキルの説明文（description）が「AやBやCのとき」と並び始めた → 分割する
必ずセットで使う2つのスキルがある → 1つに統合する
Rulesで定めたのに守られない → Hooksへ移す
Rulesに手順を書き始めた → Skillsへ移す
数秒で終わらないHooksがある → CI（PRのたびに自動で走る検査）へ移す
迷ったときは、「その内容が変わったとき、直すのは1か所だけで済むか」で確かめます。
作り方をそろえる3つの観点
作り方の基準がないと、同じ種類のスキルでも人によって品質がばらつきます。 作り方は、次の3つの観点でそろえます。
コンテキストエンジニアリング：何を、いつ、どれだけClaudeに読ませるか
プロンプトエンジニアリング：どう書けば意図どおりに動くか
ハーネスエンジニアリング：モデルの外側で何を保証し、検証するか
基本の姿勢は、確実にすべきことはハーネスに寄せて、Claudeの判断に頼る部分を減らすことです。 前の節で見たとおり、プロンプトの効き方は確率的で、ハーネスは毎回同じように動くからです。
以下の項目のうち、最初は次の3点だけ押さえれば十分です。
CLAUDE.md を短く保つ
スキルの説明文に、何をするかといつ使うかを書く
確実に守らせたいことはHooksにする
コンテキスト：必要なときに、必要な量だけ読ませる
Claudeが一度に扱えるコンテキストには限りがあり、余計な情報が増えるほど性能が落ちます。
常に読み込まれるものを最小にする
CLAUDE.md は全体方針と各資料への案内だけにします。目安は200行以内です
詳細は .claude/rules/ に分け、特定のフォルダにだけ関係するRulesは paths を指定します
CLAUDE.md の中で @ファイルのパス と書いて別ファイルを読み込む分け方では、読み込まれる量は減りません
スキルの段階的な読み込みを活かす
スキルは「説明文（常に読まれる）→ SKILL.md の本文（使うときに読まれる）→ 参照ファイルやスクリプト（必要なときに読まれる）」の3段階で読み込まれます
本文は500行以内を目安にし、詳しい内容は参照ファイルへ移します
/スキル名 で呼び出すだけのスキルは、frontmatterに disable-model-invocation: true を付けると、説明文も常時は読み込まれなくなります
中身をコピーせず、パスを書く
貼り付けた内容は、元が更新されると古いまま残るからです
大量に読む作業はAgentsに任せ、結果の要約だけを返させる
Claudeが既に知っている一般論は書かず、リポジトリ固有の規約や落とし穴に絞る
実際にどれだけ読み込まれているかは、/context で確認できます。
プロンプト：Claudeが迷わず動ける書き方にする
Rules、Skills、Agentsのファイルは、人間向けの説明書ではなくClaudeへの指示文です。
具体的に書く：「適切に」ではなく、判断基準や数値を書きます
理由を添える：書かれていない場面にも応用されやすくなります
肯定形で書く：禁止するときは理由と代わりの方法をセットにします
強調しすぎない：「必ず」「絶対」を多用すると、関係ない場面で発動しやすくなります。本当に必須のものはハーネスで強制します
例を示す：例が1つだけだとそれを真似しすぎるので、パターンが複数ある作業では例も複数示します
完了条件と出力形式を書く
自由度を作業に合わせる：壊れやすい作業は手順を厳密に書き、判断が必要な作業は方針と基準だけを書きます
スキルの説明文（description）は、Claudeがどのスキルを使うかを選ぶときの手がかりです。 「〜する。〜のときに使う」の形で、ユーザーが実際に言いそうな言葉を含めます。 他のスキルと使う場面が重ならないように書くと、似たスキルが同時に候補に挙がることも防げます。
種類ごとに書く内容は次のとおりです。
Rules：規約を「〜すること」と言い切り、理由を一言添えます
Skillsの本文：前提、番号付きの手順、成果物、最後に検証の手順を書きます
Agents：役割、判断の観点、やらないこと、返す形式を書きます
Hooks：ブロックしたときのメッセージに、理由と直し方を書きます。Claudeがそれを読んで自分で直せるからです
ハーネス：お願いではなく仕組みで保証する
ハーネスは、モデルの外側にある実行環境、ツール、制約、検証の仕組みをまとめた呼び方です。
決まった処理はスクリプトにする
フォーマットや命名のチェックはスクリプトやHooksで行います。トークンの節約になり、結果も毎回同じになります
スキル用のスクリプトは skills/<スキル名>/scripts/ に置き、SKILL.md には「このスクリプトを実行する」とだけ書きます
検証して直す流れを作る
スキルの手順に「テストやlintで確かめて、失敗したら直す」を組み込みます
エラーはClaudeに向けて返す
Hooksでブロックするときは、終了コード2で終了し、標準エラー出力に理由を書きます
ツールを実行する前のイベント（PreToolUse）なら、実行を止められます。実行後のイベント（PostToolUse）では止められず、Claudeへのフィードバックになります
権限を最小にする
settings.json のpermissionsで許可と禁止を明示し、Agentsは tools で使えるツールを絞ります。省略すると、MCPのツールを含めてすべて引き継ぎます
Hooksの変更はレビューを通す
settings.json だけでなく、SKILL.md などの冒頭の設定欄（frontmatter）に書かれたHooksも対象にします
個人の好みのHooksは、コミットしない settings.local.json に書きます
コマンドを実行するHooksの timeout の既定値は600秒と長いため、明示して上限を付けます
評価ケースを用意する
主なSkillsやAgentsに入力と期待する結果の組を用意し、変更やモデル更新のたびに結果が変わっていないかを確かめます
止める仕組み：作るときからマージ後まで
チェックがなければ、善意で作られたスキルがそのまま増え続けます。 そこで、段階ごとにチェックを置きます。
作成時（各自のPC）：Hooksと作成用スキルで、重複したものを作り始める前に気付かせます
統合ブランチ（developやmain）へのPR時：CIとレビューで、ルール違反が共有領域に入るのを止めます
マージ後（定期）：利用ログと定期の見直しで、使われないものが残り続けるのを防ぎます
必ず置く関門は、統合ブランチへのPRです。 ここを通らないと、全員には配られないからです。
作成時：作る前に気付かせる
Hooksで、.claude/skills/ や .claude/agents/ などへの新規作成（Writeツール）を、ツールを実行する前のイベントで検知します。既存の一覧と照らし合わせて、似たものがあればClaudeに知らせ、命名ルールに違反していればブロックします
作成用のスキル（例：meta-create）を1つだけ用意し、「既存の一覧を検索 → 種類を判定 → テンプレートから作成 → 台帳に登録」の流れをまとめます。作るときは必ずこれを使う運用にします
PR時：台帳とCIとレビューで止める
PR時のチェックの土台になるのが、台帳（registry.yaml）です。 共有スキルの名前、担当者、状態などを一覧にしたファイルで、チームで独自に作ります。 Claude Code自体はこのファイルを読み込まず、CIとレポートのために使います。
items:
- name: db-migration-add # スキル名（フォルダ名と一致させる）
type: skill # 種類（skill / rule / agent / hook）
owner: tanaka # 担当者
status: active # 状態（active → deprecated → 削除）
updated: 2026-09-01 # 最終更新日
CIでは、PRのたびに次の点を自動で検査します。
台帳と実体の食い違い
命名ルール（<領域>-<動作> の形で、決めた領域名だけを使う）
スキルの共通仕様（Agent Skills）が定める名前の制約（英小文字、数字、ハイフンのみで64文字以内、先頭と末尾や連続のハイフンは不可、フォルダ名と一致）
Claude Code自体はこれより緩い名前も受け付けるため、CIで確かめます
説明文の有無と長さ（Agent Skillsの上限は1024文字）、Agentsの tools とHooksの timeout の指定
分量の上限（CLAUDE.md は200行、SKILL.md は500行など）や、曖昧な表現や強すぎる表現
説明文が似ているスキル（重複の候補）
重複の判定は、簡易な方法なら説明文の文字の近さを数値にして、一定以上なら警告を出します。 ただし言い回しが違うだけで中身が同じスキルは見逃すことがあります。 精度を上げたい場合は、公式のGitHub Action（anthropics/claude-code-action@v1）を使います。 Claudeに差分と既存の一覧を渡し、重複や種類の選び方を判定させてPRにコメントさせます。
レビューの体制は、次の2つで整えます。
CODEOWNERS：.claude/ 以下の変更に、決まった担当者のレビューが付くようにするGitHubの仕組みです
PRテンプレート：既存の一覧を確認したか、なぜこの種類にしたかなどをチェック項目として載せます
マージ後：定期的に見直す
利用ログ：Hooksで、スキルやAgentsが呼び出されたことを記録します
ユーザーが /スキル名 で呼び出した場合は UserPromptExpansion、Agentsの起動は SubagentStart のイベントで記録できます
Claudeが自分の判断でスキルを使った場合の拾い方は、公式ドキュメントで確認できていません。ツールを実行する前のイベントで Skill ツールを対象にする方法が候補ですが、導入時に実際に呼び出して記録されるかを確かめます
定期レポート：月1回、使われていないもの、担当者が不在になったもの、似ているものを自動でIssueにまとめます
状態の管理：台帳の status を active → deprecated → 削除と進め、deprecated のまま残っているものはCIで警告します
判断する人の体制
CIやレポートで機械的に見つけられるのは「怪しい候補」までです。 決める人がいないと警告が無視され、また乱立が始まります。 ただし、すべてを見張る門番は要りません。 検出は仕組みに任せ、人は判断だけを行います。 似た2つのどちらを残すか、どの種類にするか、削除してよいか、方針を変えるかといった判断です。
体制は、次の3つの役割で組みます。
全体のオーナー（1人、またはサブ担当を付けて2人）
方針、台帳のルール、Hooks、CIを保守し、判断が割れたときに最終決定をします
月1回の定期レポートを見て、整理を指示します。専任である必要はなく、目安は週1〜2時間程度です
領域ごとの担当（CODEOWNERSに登録する人）
frontend、api、testなどの領域ごとに、詳しい人がPRをレビューします
作る人（全員）
作成用スキルとPRテンプレートに沿って作り、自分が作ったものの担当者として台帳に名前を載せます
オーナーのところで作業が滞らないように、次の工夫をします。
通常のPRは領域担当が承認し、オーナーは方針に関わる変更（新しい領域の追加、Hooks、CLAUDE.md）だけを見ます
この記事の判断基準をリポジトリのREADMEに書き、オーナー以外も同じ判断ができるようにします
3〜6か月ごとにオーナーを持ち回りにして、特定の人しか分からない状態を防ぎます
3〜5人程度の少人数なら、オーナー1人が領域担当を兼ね、月1回の短い見直し会を開くだけでも回ります。
導入の進め方
既存の設定を整理して基準に合わせてから、整った状態を保つ仕組みを入れます。 CIやレビューの仕組みは、これから増えるものを止めるためのもので、既に乱立しているスキルは減らせないからです。
まず着手するなら、この3つ
全部を一度に整える必要はありません。 次の3つだけでも、新たな乱立は止まり始めます。
棚卸し：リポジトリ内のスキルを一覧にして、重複を把握する
ルール：「.claude/ の変更は機能のPRと分けて、単独のPRで出す」とチームで決める
CODEOWNERS：.claude/ 以下にレビュー担当を付け、ブランチ保護で担当者の承認を必須にする
フェーズ1から7までの流れ
フェーズ1：棚卸しと分類
個人用とリポジトリ内の両方について、名前、目的、作成者、使用頻度、似ているスキルを記録し、4種類のどれに当たるかで振り分けます
見落としやすい次のものも対象に含めます
.claude/commands/（スキルに統合された、古い形式のカスタムコマンド）
サブフォルダにある CLAUDE.md や .claude/skills/
AGENTS.md（CLAUDE.md がないリポジトリで、Claude Codeが代わりに読むファイル）
共有スキルと同じ名前の個人用スキル
フェーズ2：Rulesを整える
ほかの3種類の土台になるので、先に CLAUDE.md を短くし、詳細を .claude/rules/ に分けます
フェーズ3：最小限のHooksを入れる
フォーマット、lint、危険な操作のブロックなど、反対意見の出にくいものから入れます
フェーズ4：Skillsを統合する
重複しているものは残す1つを決め、ほかの良い部分を取り込みながら、作り方の3観点で書き直します
「チーム全員が同じ結果を得るべき作業か」で共有に残すかを決め、個人の流儀に近いものは個人用に戻します
使われていないものや古いものは削除します
フェーズ5：Agentsを少数作る
レビュー担当やテスト担当など、必要性がはっきりしているものから作ります
フェーズ6：チェックの仕組みと体制を整える
台帳とCIの形式チェック、作成時のHooksと作成用スキル、Claudeによる重複判定、利用ログと定期レポートの順に入れます
あわせてオーナーと領域担当を決め、CODEOWNERSとPRテンプレートを設定します
フェーズ7：運用する
月1回の見直しで、使われていないものを deprecated にしてから削除します
個人用で良いスキルができたら、共有への昇格を提案してもらう流れを定着させます
ほかのリポジトリでも使いたいものが出てきたら、プラグインにまとめて配布します
プラグインを配るときは、リポジトリの .claude/settings.json に2つの設定を書きます。 配布元は extraKnownMarketplaces、有効にするプラグインは enabledPlugins です。 マーケットプレイスが登録されるのは、各メンバーがフォルダを信頼（trust）した後です。 プラグインの実体がマーケットプレイスの外のリポジトリにある場合は、各メンバーが自分でインストールする必要もあるため、導入手順をREADMEに書いておきます。
注意点
個人用の同名スキルが、共有スキルを隠してしまう
同じ名前のスキルが個人用と共有の両方にあると、個人用のほうが優先されます。 たとえば deploy が両方にある場合、/deploy で動くのは個人用です。 すると、同じリポジトリで作業していても、人によってClaudeの動きが変わります。
これは個人のPCの中の話なので、リポジトリのCIでは見つけられません。 個人用スキルには my- のような接頭辞を付けて、名前が重ならないようにしておきます。 共有スキルを改良したいときは、同名の個人用で上書きせず、共有スキル自体をPRで直します。
CODEOWNERSは置くだけでは承認必須にならない
CODEOWNERS ファイルを置くだけでは、担当者にレビュー依頼が飛ぶだけで、承認がなくてもマージできます。 承認を必須にするには、統合ブランチのブランチ保護（またはRulesets）で「Require review from Code Owners」を有効にします。
機能のPRに試作スキルが紛れ込む
差分が多い機能開発のPRでは、.claude/ の変更はレビューで見落とされやすく、試作中のスキルもそのままマージされることがあります。 .claude/ の変更は単独のPRで出し、試作は個人用の ~/.claude/skills/ で行います。 .claude/ に変更があるPRへCIでラベルを自動で付けておくと、見落としを減らせます。
Hooksだけでは最後の関門にならない
作成時のHooksは各自のPCで動くため、止める力には限界があります。
個人の設定（settings.local.json の disableAllHooks など）で、リポジトリのHooksを無効にできます。管理者が配布したHooksは、この設定では無効になりません
Claudeがシェルコマンドでファイルを作った場合や、人が手で作った場合は、Writeツール向けのHooksでは検知できません
そのため、最後の関門はPR時のCIにします。 組織として確実に強制したい設定は、個人では上書きできない管理者配布の設定（managed settings）で配ります。
Claudeに重複判定を任せるときは、PRに仕込まれた指示に注意する
PRの内容に悪意ある指示（プロンプトインジェクション）が書かれていると、レビューしているClaudeがそれに従うおそれがあります。 GitHub ActionでClaudeに判定させる場合は、次の対策をとります。
対象は内部メンバーのPRに限り、forkからのPRでは動かさない
Claudeに許すツールを、読み取りとコメントの投稿に絞る
ワークフローの permissions: を必要最小限にする
APIキーはGitHub Secretsで管理する
最初から厳しくしすぎない
ルールを最初から細かく決めすぎると、手続きが面倒になり、皆が個人用にこもって良いスキルが共有されなくなります。 最初は「共有するならPRを通す」だけに絞り、ルールは運用しながら少しずつ足します。 管理するのは共有領域だけにして、個人用は自由に試せる場所として残しておきます。
まとめ
スキルの乱立は個人の問題ではなく、置き場所、判断基準、作り方の基準、止める仕組みが欠けていることで起きます
4種類の仕組みを内容で使い分けて1つの大きさをそろえ、コンテキスト、プロンプト、ハーネスの3観点で作り方をそろえます
作成時、PR時、マージ後にチェックを置き、残すか消すかはオーナーと領域担当が判断します。導入は、整理してから仕組みを入れる順で進めます
まずは手元のリポジトリのスキルを一覧にして、似たものがいくつあるか数えるところから始めてみてください。
