PKSHA Technology ソフトウェアエンジニアの矢嶋です。
2025年も終わりということで、色々な人と「1年前ってどういう世界だっけ？」「Claude Code なかったね」「嘘だろ...」なんて話をしています。激動の AI 周辺では何かを標準と定めても半年後には別世界になっているかもしれませんが...サンクコストなんて言わずに探索し続けるのが正解かなと個人的には思っており、慌ただしくも楽しい1年でした。
この記事では、チームのナレッジを Claude Code のプラグインとエージェントスキルとして実装し、再利用可能な手段として活用する方法を紹介します。
背景
私たちのチームは、執筆時点で約20名のソフトウェアエンジニアが少人数のプロジェクトチームに分かれて開発しています。新規開発中のものと運用中のものを合わせると50件以上のシステムが動いています。基本的な技術スタックや設計思想はある程度揃っていますが、プロジェクトごとに要件や具体的な設計は異なります。
このような状況で課題となったのが、Claude Code や Cursor など AI ツールの活用ノウハウを共有しづらいことでした。プラグイン以前の多くの仕組みはプロジェクトスコープやユーザースコープでルールやコマンドを作成します。しかし、プロジェクトスコープの設定はそのプロジェクト固有の文脈を含むためそのままでは横展開しづらく、ユーザースコープにはプロジェクトと関係のない個人的な設定も含まれてしまいます。
Claude Code のプラグインはこの課題を解決できる仕組みであり、チームでの AI 活用において非常に強力なツールとなっています。
プラグインによる開発・共有の効率化
プラグインの導入
プラグインを利用するには、まず Claude Code にプラグインマーケットプレイスを追加し、そのマーケットプレイスからプラグインを選択してインストールします。マーケットプレイスには GitHub レポジトリやローカルファイルを指定できます。1つのマーケットプレイスには複数のプラグインを登録でき、それぞれのプラグインに対して複数のスキル、サブエージェントなどを登録できます。
例として、次のコマンドで GitHub レポジトリからマーケットプレイスを追加できます。
Claude Code 上の /plugin コマンドからも追加可能です。
claude plugin marketplace add organization/repository
マーケットプレイスを追加したら、Claude Code 上の /plugin コマンドからプラグインを選択してインストールします。
Claude Code公式プラグインをON/OFFしている様子
チームのマーケットプレイス
上述の通りマーケットプレイスとして GitHub レポジトリが利用できます。Claude Code でマーケットプレイスを追加するときに裏で動く Git 操作は自分の local 設定に応じて行われるため、プライベートレポジトリでも問題なく利用できます。
マーケットプレイス用として Organization 配下にプライベートレポジトリを作成し、チームの規約や知識をプラグインとしてパッケージングして登録します。
プラグインの便利な点として、プラグイン単位で手軽に ON/OFF を切り替えることができます。共通化した規約や知識が特定のプロジェクトに適さない場合は該当するプラグインを OFF にすれば影響を受けずに Claude Code を利用できます。プラグイン開発側としても、実験的なプラグインや個人の好みが反映されるようなプラグインを気軽に追加できるメリットがあります。
各スコープの設定とプラグインの共存イメージ
一方で、プラグインを有効にした場合、そのプラグインに含まれるスキルやコマンドは一括で有効になります。そのため、プラグインをどのような粒度で作成するかについては、チームで議論しながら設計してください。
まだまだ模索中ですが、現時点で私たちのチームでは以下の構成にしています。
.claude-plugin
├── marketplace.json
├── plugins
│ ├── core // Git操作、ブランチ命名規約、コミットメッセージ規約など共通の規約・知識
│ │ ├── commands
│ │ └── skills
│ ├── dev-guideline // 特定のプロジェクトや設計方針に強く依存しない開発知識・規約
│ │ └── skills
│ │ ├── python-guide
│ │ └── shellscript-guide
│ └── experimental // 実験的に作成したものを気軽に配置する場所
│ ├── agents
│ └── commands
└── scripts // プラグインの簡単なバリデーションスクリプト
├── validate-marketplace.sh
├── validate-plugin-manifest.sh
└── validate-plugin-structure.sh
プラグインの開発
チームのナレッジとしてのプラグインをメンテナンスする場合、マーケットプレイスのレポジトリで開発します。GitHub レポジトリをマーケットプレイスとして使うと手元の実装を反映するのに一手間かかりますが、ローカルのパスを指定すると開発中のコードが即座に反映されるため、ストレスなく開発できます。
なお、同じ名前のマーケットプレイスを登録できないため、GitHub をマーケットプレイスとして登録済みの場合は一度マーケットプレイスをアンインストールしてからローカルパスを指定して追加しなおします。
# 既存のマーケットプレイスを削除
claude plugin marketplace remove marketplace-name
# ローカルディレクトリからマーケットプレイスを追加
claude plugin marketplace add /path/to/marketplace-repo
プラグインを作成する際はマーケットプレイスマニフェストやプラグインマニフェストを作成して対応したファイルを配置しますが、具体についてはこの記事では割愛します。
プラグイン利用側のアップデート追従
プラグインには更新機能があり、Claude Code の /plugin コマンドからプラグインを選択して「Update now」を実行することで、プラグインを更新できます。マーケットプレイス自体の更新についても、同様に /plugin コマンドからマーケットプレイスを選択して「Update marketplace」を実行することで更新できます。
Claude Code 2.0.70からはマーケットプレイスの自動更新機能が追加され、アップデートへの追従がさらに楽になりました。
エージェントスキルによる開発ナレッジの実装
エージェントスキルの概要
エージェントスキルの詳細についてはこの記事では深く触れませんが、簡単に説明すると、SKILL.md というメインファイルと、そこからリンクされた参考ドキュメントや実行用スクリプトで構成されるパッケージです。
公式ドキュメントでは以下のように説明されています。
エージェント スキルは、専門知識を発見可能な機能にパッケージ化します。各スキルは、Claude が関連する場合に読む指示を含む SKILL.md ファイルと、スクリプトやテンプレートなどのオプションのサポート ファイルで構成されています。
Anthropic 公式が提供している skill-creator スキルの構成を例として示します。
.
├── LICENSE.txt
├── references // スキル設計のプラクティスを書いた参考ドキュメント
│ ├── output-patterns.md
│ └── workflows.md
├── scripts // スキルの初期化、バリデーションなどのスクリプト
│ ├── init_skill.py
│ ├── package_skill.py
│ └── quick_validate.py
└── SKILL.md // スキルの本体。ここから各ファイルを参照する
スキルの仕組みでは、以下の3段階で「段階的な情報開示」を実行します。
- 常に読み込まれるメタデータ（SKILL.md の YAML フロントマター）
- トリガーされたときに読み込まれる指示（SKILL.md の本文）
- 要求時に読み込まれるリソースとコード（参照ドキュメントやスクリプト）
常にコンテキストに含まれるメタデータはスキルの name と数十〜数百文字の description だけであり、トリガーされたときも SKILL.md のみがコンテキストに含まれます。参照ドキュメントやスクリプトは必要になった場合にのみ読み込まれるため、個々のドキュメントを充実させてもコンテキストを圧迫しません。
スキルという仕組みがない時期やツールにおいても、docs フォルダにドキュメントを配置して AGENTS.md から参照させるなどの工夫は可能でした。スキルはこのような手法を明確な仕組みとして組み込んだような形です。
チームの開発ナレッジのスキル化
このエージェントスキルの仕組みを活用して、チームの開発ナレッジを Claude Code から利用可能な形で整備しています。
前述の dev-guideline プラグインに含まれるスキルから抜粋した例は以下の通りです。
.
├── README.md
└── skills
├── python-guide
│ ├── pytest-best-practices.md
│ └── SKILL.md
└── shellscript-guide
├── minimum-safe-bash-script-template.md
└── SKILL.md
チーム内の会話で「テストを書かせるのは便利だが、何でもモックする、アサーションが弱い、Parameterized Test を使ってくれない」といった不満が出てきました。そこで、これらの問題に対処するためのベストプラクティスを具体的に示した pytest-best-practices.md を作成し、python-guide スキルの SKILL.md から参照する形にしています。
同様に、チームの勉強会で「セキュアなシェルスクリプトの書き方」として紹介された Minimal safe Bash script template もスキル化しています。
言語やライブラリの一般的な知識はモデル自身が持っているため、負債化を避けるため基礎的な内容は極力書かず、実際に Claude Code を使う中で感じた不満に対処する形でスキルを育てています。チームの勉強会や Slack での会話をそのまま Claude Code に投入し、議論しながらスキル化していくことで、手軽にチームの知識を注入できます。
まとめ
- ユーザースコープやプロジェクトスコープでは共有が難しかったナレッジを、プラグインを利用することで効率的にチームへ展開できる
- チームの開発規約やプロジェクトに依存しない開発知識をスキル化することで、コンテキストを圧迫せずに Claude Code から参照できる
- 従来は人間向けに作成していた「文章」が、スキルやプラグインにすることで開発を直接的に支援する「再利用可能な手段」になる
エージェントスキルは元々Claude Code 固有の機能として2025年10月にリリースされましたが、2025年12月18日にオープンスタンダード化され、CursorやCodexなど他のツールでも利用可能になりました。
私たちのチームは Claude Code に限定しているわけではなく、1人あたり$200の予算（執筆時点）の中で、各メンバーがその時々で最適なツールを模索しています。スキル化のデメリットとして Claude Code 限定になることを懸念していましたが、スタンダード化によって他のツールでも利用可能になり、スキルとして整備するモチベーションがより高まりました。
開発ナレッジの整備と活用として、プラグインとスキルの活用をぜひ試してみてください。個人的にはプラグインの仕組みも非常に魅力的なので、Codex や Cursor でも使えるように標準化されることを期待しています。
Discussion