Agent Skillは振る舞いとナレッジを分けて設計する

Claude Codeを社内に広めるとき、多くの企業が直面する課題がある。便利なスキルを書くほど、それが膨らみ、メンテナンスが地獄になる。「PR作成」というスキルが、リント・テスト・コミット・プッシュ・PR作成をすべて内包していて、チーム全体で「このステップだけは飛ばしてほしい」という注文が増えると、スキルは特例だらけになる。その企業の実践例が示したのは、この腐敗を止める方法だ。「振る舞い」と「ナレッジ」を分ける。

PRレビュースキルで具体化すれば、SKILL.mdには「変更箇所から調査を始め、周辺コードへ広げ、レビュー観点に従い、問題を説明して返す」というやり方だけ書く。一方、「どのような観点を見るべきか」は別ファイルのreview-guidelines.mdに列挙する。「名前と実装が一致しているか」「既存の動作を壊していないか」「設計に矛盾がないか」といった項目を、ここに追加していく。すると不思議なことに、スキル本体にはほとんど修正が必要なくなり、ナレッジの側だけが膨らみ続ける。これはソフトウェア設計の「関心の分離」がそのまま当てはまった例だ。

このやり方のメリットは単なる保守性向上に留まらない。複数の職種が同じスキルを使う企業なら、「バックエンド向けレビュー観点」「インフラ向けレビュー観点」といったナレッジを追加することで、スキル本体の振る舞いは不変のまま配布を広げられる。自社のAIエージェントやプロンプトスキルを育てるなら、初期段階から「何を変更しやすくするか、何を固定するか」を設計に組み込むことだ。その分離がなければ、半年後には誰も触りたくない負債になる。