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を読ませる」へ変わります。

その差は、案件が増えるほど効いてきます。