AI駆動開発向けSkillsをsubmoduleで共有運用するための実践構成
AIコーディングエージェントを使った開発が広がるにつれて、プロジェクトごとに同じような指示を書き直す場面が増えてきました。
たとえば、次のようなルールです。
- API設計では後方互換を重視する
- DB設計では
NOT NULLや制約の意図を明確にする - コードレビューでは差分の見た目ではなく回帰と保守性を見る
- ジョブ設計では冪等性と再試行戦略を外さない
これらを毎回プロンプトに埋め込む運用は、短期的には成立します。しかし、Skillが増えるほど再利用性と保守性が落ちます。
そこで、私は Codex向けのSkillsを別リポジトリとして持ち、それを各案件へ git submodule で配布する 形に寄せています。
この記事では、その運用について整理します。
この記事の前提
対象は、次のようなチームや個人です。
- CodexやClaudeCodeを日常的に使っている
- 複数案件で共通の開発ルールを使い回したい
- PDFや社内資料から再利用可能な
SKILL.mdを作って蓄積したい - 案件固有の知識と、横展開したい知識を分けて管理したい
逆に、単一リポジトリだけで完結するなら、ここまでの構成は不要です。
結論
先に結論を書くと、構成は以下で十分です。
- 共通Skills専用のリポジトリを作る
- 各案件には
git submoduleで取り込む - 利用先リポジトリの
AGENTS.mdからSkills探索を明示する - 各
SKILL.mdにはnameとdescriptionを必ず持たせる - 1 Skill = 1 job を守る
- 一次情報は参考欄へ寄せ、本文は汎用原則として書く
重要なのは、submodule は配布方法であって、認識そのものは AGENTS.md と SKILL.md のメタデータで支える、という点です。
なぜsubmoduleなのか
subtreeやコピー運用でも配布自体はできます。
それでもsubmoduleをベースにする理由は、次の3つです。
1. 共通資産の更新を一元化しやすい
各案件に同じMarkdown群を直接持たせると、改善が入ったときに横展開が重くなります。
submoduleなら、共通リポジトリ側で改善し、利用先では更新タイミングだけを制御できます。
2. 案件固有知識と共通知識を分けやすい
Skillsの墓場化は、共通ルールと案件事情が混ざるところから始まります。
共通repoには「どこでも使う判断ルール」だけを置き、案件固有の事情は本体repo側に残す方が、長く保守できます。
3. 運用責任の境界が明確になる
どこまでが共通ルールで、どこからが案件ローカルかを切り分けやすくなります。
これはAI運用でも重要です。Skillの品質責任を共通repo側へ寄せられるからです。
基本構成
共通repo側は、たとえば次のような構成です。
skills/
common/
skill-creation/
research/
engineering/
api-design/
database-design/
coding-standards/
batch-and-job-design/
configuration-management/
data-science/
product/
template/
AGENTS.md
README.md
利用先では、これをsubmoduleとして取り込みます。
git submodule add <skills-repo-url> tools/development-skills
git commit -m "chore: add development-skills submodule"
AIに使わせる主導線
ここが一番誤解されやすいところです。
submoduleとして置いただけでは、AIが自動で全部読みに行くとは限りません。
AIに拾わせる主導線は、実際には次の2つです。
- 利用先リポジトリの
AGENTS.md - 各
SKILL.mdのdescription
利用先 AGENTS.md に書くべき最低限
たとえば、利用先リポジトリでは次のように書きます。
# 共通Skillsの利用
作業前に `tools/development-skills/skills` 配下の `SKILL.md` を確認する。
各Skillの YAML frontmatter にある `name` と `description` を優先して見て、現在のタスクに最も具体的に一致するSkillを使う。
該当Skillがない場合は通常のリポジトリ規則に従う。
これで、少なくとも「まず共通Skillsを見る」という導線は作れます。
SKILL.md の設計原則
共通repoを運用していて、実際に効くのは次のルールです。
1. 1 Skill = 1 job
「API設計全部」や「開発全般」のような大きすぎるSkillは、発火条件も本文もぼやけます。
よいSkillは、だいたい次の粒度です。
- API設計と契約
- DBスキーマ設計
- コードレビュー原則
- バッチ/ジョブ設計
- 設定とシークレット管理
2. description は「何か」ではなく「いつ使うか」を書く
悪い例:
description: This skill is about API design.
よい例:
description: Use this skill when designing, changing, reviewing, or documenting APIs, especially input/output contracts, errors, compatibility, and versioning.
発火の入口は、説明タイトルではなく利用場面です。
3. 本文は汎用原則、参考欄は一次情報
これはかなり重要です。
たとえばAPI設計Skillに一次情報としてGoogleのAIPを使うのは有効です。ただし本文で
- AIP-122 に沿って
- AIP-131 に沿って
- AIP-193 に沿って
のように番号を並べ始めると、Skillの読み味が急に製品依存になります。
そのため、本文は次のように抽象化します。
- resourceを安定識別子で表す
- 標準操作で表現できるものは標準操作へ寄せる
- 一覧取得はページングを前提にする
- エラーは機械可読な構造を持たせる
- 互換性を壊す変更はメジャーな変更として扱う
そのうえで参考欄に一次情報を置きます。
この分離をやらないと、Skillはすぐに「特定規格の写経」になります。
共有repoに残すべきもの、残さないもの
残すべきもの
- 複数案件で繰り返し使う判断基準
- 実装前レビューや設計レビューで使えるチェックリスト
- 技術選定や運用設計の原則
- 一次情報を咀嚼したうえでの汎用ルール
残さない方がよいもの
- 案件固有の業務フロー
- 特定顧客の命名規則
- 一時的なトラブルシュートメモ
- ローカルパスや添付前提の手順
- プロンプトを貼っただけの文章
共通repoに残す価値があるかの基準は、かなり単純です。
3回以上、別文脈で再利用されるか を目安にするとぶれにくくなります。
墓場化を防ぐための運用
Skills repo は、放っておくとすぐに増殖します。
増殖を防ぐには、追加基準と廃止基準を先に決める方が早いです。
追加基準
- 既存Skillで代替できない
- 1つの仕事に閉じている
- 具体的な入力と出力が言える
- 一次情報または明確な実務根拠がある
廃止・統合基準
- 半年使っていない
- 似たSkillが複数ある
- titleだけ違って中身が同じ
- 案件固有化している
また、index.md は目次として保ち、本文を寄せ集めない方がよいです。
Skill Loader は必要か
私の整理では、通常は不要です。
もしsubmodule運用を前提にするなら、まず必要なのは
AGENTS.md-
SKILL.mdのdescription
であって、独自ローダーではありません。
manifest.yaml のようなファイルは、
- 独自ツールを作る
- Skill一覧を他システムでも読む
- 検索UIや自動選択を追加したい
といった段階になって初めて意味が出ます。
したがって、最初からローダー前提で設計するより、submodule + AGENTS.md + description で回る形を先に作る方が現実的です。
この構成の向き・不向き
向いている
- 複数案件で共通ルールを使い回したい
- 技術顧問や開発コンサルのように横断支援したい
- AIに毎回同じ指示を書くのを減らしたい
- PDFや書籍から再利用可能なルールへ落としたい
向いていない
- 単一repoでしか使わない
- 共通化より案件速度を優先したい
- まだSkillの粒度や品質基準が固まっていない
まとめ
AI駆動開発向けSkillsの運用で重要なのは、以下のような仕組みになります。
- 共通repoを分ける
-
git submoduleで配る - 利用先
AGENTS.mdで探索導線を作る -
SKILL.mdに発火しやすいdescriptionを書く - 1 Skill = 1 job を守る
- 本文は汎用原則、参考欄は一次情報にする
この形にしておくと、AIへの指示は「毎回全部説明する」から「必要なSkillを読ませる」へ変わります。
その差は、案件が増えるほど効いてきます。