skillsに全振りしてdocs,rules,commandsを削るコスパ重視のハーネス実装案
はじめに
最近いろいろなプロジェクトを見ていると、Claude Code、Codex、GitHub Copilot、Cursor、Gemini、OpenCode などを併用している人ほど、
結局、プロジェクトにどうハーネス実装するのが一番いいのかわからない
という悩みにぶつかりがちです。
それぞれ微妙に思想も構造も違うので、全部にきれいに合わせようとすると、どうしても管理が重くなります。
そこでこの記事では、全プロバイダー対応を強く意識しつつ、できるだけコスパよく運用する構成を提案します。
結論から言うと、プロジェクトルートに skills/ だけ置く、これがかなり強いです。
各種プロバイダーの専用 skills フォルダは無視していいのか
ルートに置いたら、各プロバイダーの期待する構造に乗らない。
その結果、コンテキストに乗らず、エージェントが適切な場面で使えないのでは？
これはもっともな疑問です。
実際、ルートに skills/ を置いただけでは、title や description が自動でコンテキストに乗らず、デフォルトではエージェントが反応しにくくなります。
つまり、そのままでは適切なタイミングでの自動適用は弱くなる、これは事実です。
ただし、ここは 検索で解決できます。
スキル検索に特化した検索システムを整えておけば、必要なときに必要なスキルを引けます。
（そもそもその検索システムをどうやるの？と思われた方もいると思いますが、ハイブリッド検索かつ、定期検索精度自動改善の方法は別の記事でやろうと考えています。さらっとだけ説明するとトリガーワードをつかったりセマンティックにフォールバックを入れられると高いベンチマークを出しやすいです）
しかもスケーラビリティの観点では、むしろ最初から全部がコンテキストに乗らないことにメリットがあります。
なぜなら、title と description だけとはいえ、何十、何百と増えていくと、その総量は無視できないからです。
常時全部を読ませるより、必要なものだけ検索で拾うほうが合理的です。
さらに、本当に自動反応してほしいものだけは、CLAUDE.md や AGENTS.md に Markdown テーブルで一覧化しておけば十分です。
つまり、
- 常時読ませたい少数の重要スキル
- 検索で拾う多数のスキル
この二段構えにできます。
そしてもうひとつ大きいのが、重複管理の問題です。
各プロバイダーごとの構造に合わせて、同じスキルを複数箇所に持つ運用は、最初はなんとか回っても、あとからかなり面倒になります。
シンボリックリンクで逃がすこともできますが、結局、構造が増えること自体の複雑さは消えません。
要するに、ルートにまとめることで、
- 重複管理
- スケーラビリティ
この2つをかなりきれいに解消できます。
だったら、プロジェクトに置かず、スキル専用の別リポジトリで管理すればいいのでは？
という考え方もあります。これは実際かなり良いです。
ただ、プロジェクトごとに最適化された固有スキルが必要になる場面はどうしてもあります。
なので、完全に外出しだけで済むわけではなく、共通スキルは外部、プロジェクト固有スキルはその場に置くという使い分けが現実的です。
docs を削いでもいい理由
docs/ は古典的なプロジェクト構造として非常によくありますし、実際わかりやすいです。
ただ、この記事ではあくまでコスパ最重視で考えます。
その観点でいうと、docs はあってもよいけれど、機能的には skills で代替しやすいです。
なぜかというと、skill にしておけば、ただの文章にとどまらず、あとから拡張できるからです。たとえば、
-
scriptsを混ぜて指示を軽量化する -
referencesに分割して肥大化を防ぐ - 実行可能な手順に寄せる
- 検索対象として統一的に扱う
といったことができます。
もちろん、docs/ の中にフォルダを切って整理する運用もできますし、従来の CLI ベースのやり方で十分な場面もあります。
ただ、「最終的に扱いたい単位」をどちらに寄せるかで考えると、skills のほうが拡張性があります。
なので、
docs は残してもいい。
でも、どちらか一方しか残せないなら、skills を残す。
というのがこの記事の立場です。
統一してしまえば、無駄な管理も減ります。
docs-to-skills のような移行補助のメタ管理をわざわざ作る必要も薄くなります。
特にスキルが何十、何百と増えてくると、すべてを CLAUDE.md や AGENTS.md に列挙するのは現実的ではありません。
その段階では、どうしても
- 優先度の高いものだけ表に載せる
- あとはトリガーワードテーブルを使う
- 足りない部分はセマンティック検索でフォールバック
というハイブリッド検索運用に寄っていきます。
この検索自体は、並列で、最適化したりトリガーワードはセッション解析から定期的に改善できるとなお良しです。
そうなるなら、最初から docs と skills を分けて持ち続けるより、skills に寄せて一元化するほうが構造コストは低いです。
もちろん、ただの Markdown として置いておくことには、
- 読むだけの責務に絞れる
- 実行性を持たないので気軽
- 古典的な構造として理解されやすい
といった利点もあります。
なので、ここは「docs はダメ」ではなく、
コスパ重視なら skills に寄せたほうが得、という整理です。
rules を削いでもいい理由
rules はとても便利です。
とくに path ベースで発動できる仕組みは、特定ディレクトリ配下にだけルールを効かせたいときに強いです。
ただ、全プロバイダー対応を考えると、この便利さはそのまま統一性にはつながりません。
あるプロバイダーでは path specific に細かく制御できても、別のプロバイダーでは同じ感覚で扱えない、というズレが起きやすいからです。
このズレを無理やり埋めようとすると、
- どれかを SSOT にする
- 共有用の skill を作る
- 各プロバイダー向けに変換・配布する
といった運用が必要になり、管理コストが一気に上がります。
しかも、厳密に揃えようとすると、ディレクトリごとに AGENTS.md や GEMINI.md を配置するような話にもなりがちです。
これは確かに実現可能ですが、コスパが良いとは言いにくいです。
そこで本記事では、rules でやりたかったことの多くは、skills の検索で代替できるという立場を取ります。
たとえば、ある機能を実装したいときには、まずその機能に対応する skill を検索する。
もし途中で特定の path 配下にだけ特別なルールが必要なら、そのことが skill の description から引っかかるように設計しておく。
この運用で、かなりのケースは回せます。
もちろん、path ベースで自動発火するルールが便利な場面はあります。
ただ、実務ではそこまで厳密な path 制御が必要なケースばかりではなく、機能単位・作業単位で反応できれば十分なことも多いです。
つまりここで言いたいのは、
path specific な rules は便利。
でも、全プロバイダー統一とコスパを優先するなら、skills 検索で吸収するのも現実的な実装
ということです。
commands を削いでもいい理由
commands は slash command 的に使えて便利です。
しかも title や description が常時コンテキストに乗るわけでもないので、軽く使うにはかなり相性がいい仕組みです。
ただ、全プロバイダー対応という観点では、やや立場が弱くなります。
なぜなら、コマンド周りの扱いは各プロバイダーで揺れやすく、長期的な共通基盤として見ると、skills ほど安定した中心にはしづらいからです。
また、commands は便利ではあるものの、拡張性は skills に劣ります。
- references を持たせる
- scripts を混ぜる
- 実行手順を定義する
- 検索対象に組み込む
- 後からより高度な自動化へ伸ばす
こういったことを考えると、最初から skill として定義しておいたほうが後々ラクです。
しかも、検索ベースの skill 運用を前提にするなら、
スキル名を覚えて名指しで呼んでもいいし、ルートの skills/ からパス指定やドラッグ＆ドロップ的に扱うこともできます。
つまり、
commands は便利だが、
全プロバイダー対応と将来拡張を優先するなら、skills に寄せても大きな問題はない。
というのがここでの結論です
まとめ
ここまでの話をまとめると、構造として docs、rules、commands が存在すること自体はまったく悪くありません。
ただし、全プロバイダー対応と管理コストを同時に考えると、中心を skills に寄せる方針はかなり筋がいいです。
つまり、この記事の提案はこうです。
- プロジェクトルートに
skills/を置く - 本当に常時見せたいものだけ
CLAUDE.mdやAGENTS.mdに載せる - それ以外は検索でトリガーワード込み、セマンティックフォールバックありの検索システムで拾う
- docs / rules / commands でやっていたことも、できるだけ skills に寄せる
この構成にすると、全体の構造がかなりシンプルになります。
もちろん、各プロバイダーの仕組みをフル活用したいなら、専用構造を使い分ける方向もあります。
その場合は、sharing 系の skill を作って、各プロバイダー向けに規約的に share していくのが現実的だと思います。
ただ、まず最初の一歩として、そして長く破綻しにくい構成としては、
とりあえずルートに skills/ だけ置く
これはかなりコスパの良い選択肢です。
最近ハーネス周りの導入支援を積極的に行なっていますので、もしご興味がある方がいらっしゃたらお気軽にお声がけください
Discussion