この記事は「コドモンAdvent Calendar 2025」16日目の記事です🎅
こんにちは。プロダクト開発部の友野です。
記事公開のこの日、誕生日を迎えました*1。身体の成長（老化かもしれない）だけでなく、開発者としてのスキルも磨いていきたいところです。
そんな "スキル" つながりで、今回はClaudeの新機能「Agent Skills」を取り上げます。本記事では、Agent Skillsを活用したコンテキスト管理をテーマに、複数チームで開発しているモノリスプロダクトでの知識管理について考えていきます。Claude Codeを使い始めた方、特に複数チームで開発しているプロダクトに携わっている方の参考になれば幸いです。
はじめに：CLAUDE.mdの役割が変わる
先日、「生成AIと共に、長期運用プロダクトのさらなる成長を加速させるための実践知 LT」というイベントにて、『長期運用プロダクトこそ効くコンテキスト管理の妙』というタイトルで発表しました。
発表の要旨は以下のようなもので、CLAUDE.mdの重要性を説く内容でした。
- 長期運用プロダクトほど、生成AIを活用するにはコンテキスト管理が肝になる
- 長年の暗黙知をCLAUDE.mdに教え込む
- タスクごとにClaudeとふりかえりをしながらCLAUDE.mdを育てていく
しかし、CLAUDE.mdを中心としたコンテキスト管理には、組織的に活用を進めていく上で懸念がありました。次のセクションでその課題を整理した上で、解決策となりうるAgent Skillsを紹介します。
組織的な活用が進んだときのCLAUDE.md運用の懸念
コドモンは保育・教育施設向けのSaaSプロダクトで、ローンチから約10年が経過しました。部分的にマイクロサービス化が進んでいるものの、メインプロダクトは依然としてモノリスな構成です。
このモノリスな構成には多数の機能、多数のコンテキストが配置されています。登降園管理、請求管理、保護者連絡、施設管理、etc. ……。それぞれのコンテキストを、複数のチームが並行して保守開発しています。
さて、このような状況でCLAUDE.mdを運用していくと、どうなるでしょうか。
日を追うにつれて、CLAUDE.mdには様々な知識が蓄積されていくことが予想されます。フロントエンドの実装パターン、バックエンドのAPI設計方針、新しく導入した技術スタックの使い方…。さらに、各チームが担当コンテキストのドメイン知識を追記していくこともあるでしょう。
ここで懸念されるのは、これらの情報がCLAUDE.mdに書かれていることで、起動時に全て読み込まれることです。
例えば、私が所属する新市場向け機能開発チームは、保護者からの連絡体験を中心としたコンテキストを担当しています。 このチームにとって、自チームでは採用していない実装戦略や、請求業務のドメイン知識は必要ありません*2。にもかかわらず、CLAUDE.mdに書かれている以上、毎回読み込まれてしまいます。
結果として、タスクに関係ない情報がコンテキストを圧迫し、Claudeの思考が遅くなり、あまつさえ不正確な推測をするおそれがあります。
さらに厄介なのは、知識をどこまで書くかという判断の難しさです。CLAUDE.mdに書けば他のタスクでも読み込まれてしまう。かといって書かなければ、毎回Claudeに同じ説明をする羽目になる…。
そんな板挟みを解消してくれるのが、Agent Skillsです。
Agent Skillsとは何か
基本概念：Claudeが自律的に参照する知識ファイル
Agent Skillsは、Claudeが必要に応じて自動で読み込む知識ファイルです。SKILL.mdというMarkdownファイルに、YAMLフロントマターで名前（name）と説明（description）、そしてスキル本文を記述します。
--- name: スキル名 description: スキルの説明といつ使うか --- # スキル本文 ここに知識を記述する
ポイントは、Claudeがタスクに応じて必要なスキルを自動で判断し、読み込むという点です。明示的に「このスキルを使って」と指示する必要はありません。
Progressive Disclosure：必要な知識だけを段階的にロード
スキルの読み込みは段階的に行われます。
- 起動時：スキルのnameとdescriptionだけを読む
- 実行中：タスクに関連すると判断したら、スキル全体を読む
- 実行中：さらに必要であれば、スキルで定義されたスクリプトやファイルを読む
これがProgressive Disclosureと呼ばれる仕組みです。
起動時にはnameとdescriptionだけが読み込まれ、タスクに関連するスキルのみが後から読み込まれます。APIの実装タスクならapi-conventionsスキルだけ、テスト作成タスクならtesting-guidelineスキルだけ、といった具合です。
スキルの3分類と使い分け
スキルには、配置場所と共有範囲によって以下の3つの分類があります。
- Project Skills
- Plugin Skills
- Personal Skills
(1) Project Skills（リポジトリ共有）
Project Skills（プロジェクトスキル）は、リポジトリの.claude/skills/ディレクトリに配置します。コードベースと同じ場所で管理されるため、リポジトリをクローンした開発者全員が同じスキルを利用できます。
awesome-project/
└── .claude/skills/
├── architecture/SKILL.md
├── api-conventions/SKILL.md
└── testing-guideline/SKILL.md
開発者全員が同じスキルを利用できるということは、以下のような内容が適していると考えられます。
- 設計原則、アーキテクチャの説明
- API規約、コーディング規約
- テスト方針
- 共通のドメイン知識
これらは当該リポジトリで開発する人なら誰でも知っておくべき知識です。例えば、「このプロジェクトではクリーンアーキテクチャを採用しており、ドメイン層は他の層に依存しない」といったアーキテクチャの判断や、「APIのエンドポイントは/api/v1から始め、RESTful API設計原則に従う」といった規約が該当します。
Gitで管理されるため、知識の変更履歴が残り、プルリクエストでレビューもできます。新しくチームに参加したメンバーも、リポジトリをクローンするだけでこれらの知識を活用できるようになります。
プロジェクト全体で共有すべき知識、つまりCLAUDE.mdに書いていたような内容の多くは、Project Skillsに移行できます。
(2) Plugin Skills（チーム共有）
特定のチームだけが必要とする知識は、Plugin Skills（プラグインスキル）として管理できます。プラグイン経由で配布することで、チームメンバー全員が同じスキルを利用できます。
Project Skillsと異なり、プラグインをインストールした開発者=チームメンバーの範囲でスキルを共有するので以下のような内容が適していると考えられます。
- チーム固有の設計ドキュメントやレビューの開発プラクティス
- issue対応時にチームの約束ごととして決めたタスクリスト
これらの知識をProject Skillsとして.claude/skills/に置くと、他チームの開発時にも読み込み対象になってしまいます。チーム固有の知識はPlugin Skillsとして分離することで、他チームに影響を与えずに済みます。
なお、プラグインはGitHubに構築したマーケットプレイスを通じて比較的簡単に配布できます。詳細は公式ドキュメントを参照してください。
(3) Personal Skills（個人用）
Personal Skills（パーソナルスキル）は、~/.claude/skills/に配置します。この場所に配置したスキルは、どのプロジェクトで作業しても自動的に利用可能になります。
個人的な用途に限定されるので、主に個人の環境に紐づく設定が適していると考えられます。
- 使用しているシェル（fish、zshなど）に合わせたスクリプト例の出力形式
- エディタ環境に依存した操作説明の好み
もし個人で育てたスキルがチーム開発の文脈で有用であれば、属人化を避けるためにもPlugin SkillsやProject Skillsとしてチームに共有する方がよいかもしれません。
使い分けの判断基準
どのスキルに何を書くか迷ったときは、以下の基準で判断できます。
| 判断基準 | 配置先 |
|---|---|
| リポジトリを保守する全員で共有すべき知識 | Project Skills |
| 特定のチームだけが必要な知識 | Plugin Skills |
| 個人の好みや作業スタイル | Personal Skills |
チームでの活用例
最後に、私が所属するチームでの活用例を紹介します。
担当するコンテキストのドメイン知識をProject Skills化する
私のチームでは現在、保護者からの連絡体験の改善を主に担当しています。扱うコンテキストには、連絡の種類（欠席・遅刻・早退など）や状態遷移、登降園予定との関連といったドメイン知識があります。
CLAUDE.md運用の懸念のセクションでも触れたとおり、基本的に他チームは、日頃の開発ではこれらの知識は必要ありません。 CLAUDE.mdに書くと毎回読み込まれてしまいますが、Project Skillsとして定義すればProgressive Disclosureにより必要なタスクでだけ読み込まれます。他チームが連絡管理のコンテキストに触れるときにも参照できるよう、Plugin SkillsではなくProject Skillsとして配置しています*3。
チームの開発プロセスをPlugin Skills化する
チームではGitHubのissueを使って、APIテスト、ドメイン層やユースケース層ごとにリスト形式でタスク管理をしています。このタスクリストのテンプレートと、タスクの分割粒度などをスキル化することで、Claudeと開発者で同じ認識のもと対応計画を立てられています。
テスト駆動で行うなど、チームごとの仕事の進め方は大局的には似ている部分もありますが、細かいプロセスを共通知識とするためにPlugin Skills化して日々の開発に取り組んでいます。対象のリポジトリのCLAUDE.mdはシンプルに保ちつつ、自分たちの進め方に必要な知識だけを管理できるという点が優れています。
まとめ
誤解を恐れずに言えば、Agent Skillsは、ポータブルで組み合わせ可能なCLAUDE.mdのようなものを実現できる仕組みです。 長期運用されているモノリス構成のプロダクトにおいて、意図しない他チームへの影響を避けてチーム固有の知識を管理できる点は魅力的です。
CLAUDE.mdを育てる時代から、スキルを設計する時代へ。コンテキスト管理の次のアプローチとして、Agent Skillsはとてつもない可能性を秘めています。
まだこれらの取り組みは始めたばかりですが、チームのふりかえりを通じて効果を感じています。実践を通じた新しい学びや気づきがあれば、また別の機会にお伝えできればと思います。
