TL;DR
- SkillsBench 論文の知見をもとに、GitHub Copilot の「スキル」に品質基準を設けました
- Copilot coding agent に Issue → PR まで自走させ、人間が GPT のレビュー観点で品質を担保しました
- 結果:設計ドキュメント 4 本 + CI ワークフロー 1 本が約 30 分で着地しました
- 人間の役割は「設計判断」と「レビュー観点の選定」だけで、コードはすべて Agent が書きました
背景:なぜスキル品質が問題になったのか
Copilot のスキルとは
GitHub Copilot coding agent は、リポジトリ内の skills/ 配下にある Markdown(例:skills/**/SKILL.md)を読み込み、タスク遂行の判断材料にします。
ざっくり言うと **「Agent が参照する指示書」**です。
Copilot coding agent とは(読者向け補足)
Copilot coding agent は、Issue に書かれた目的・制約・完了条件をもとに、実装案を立てて PR を作り、指摘を受ければ修正コミットを積み上げていくタイプのエージェントです。
(人間は Issue とレビューに集中し、コーディングや修正の実働は Agent に寄せられます)
現状の問題
私たちのリポジトリ(MCP セキュリティ監視)には 8 つのスキルがありましたが、SkillsBench 論文(arXiv:2602.12670)の観点で見ると アンチパターンに寄りがちな状態でした。
| 指標 | 現状 |
|---|---|
| スキル総数 | 8 |
| 合計行数 | 1,608 行 |
| 推定トークン | ~22,600 |
| YAML frontmatter | 0/8(全スキルに無い) |
| 完了条件の記述 | 0/8 |
| 最大行数 | 285 行(evidence-capture) |
SkillsBench が教えてくれたこと(ざっくり要点)
SkillsBench は、同じタスクを「スキルなし / 人間設計スキルあり / AIが自作したスキルあり」で多数回試行し、成功率を比較しています。
ここで言う「成功率」は、各タスクに対して 指定された完了条件(正答基準)を満たせた割合です。
(※論文内の定義やタスクごとの判定ロジックに依存します。ここでは「スキル有無で達成率が有意に変わり得る」という主張の根拠として参照しています)
特に刺さったのは次の方向性です。
- 短く・絞ったスキルは効きやすい(逆に網羅的すぎると悪化し得る)
- 同時に読ませるスキル数が増えるほど効き目が落ちたり、逆効果になったりし得る
- 「スキルを増やせば良くなる」は成立しないケースがある
つまり「短く」「必要なときだけ」「少数を読む」が基本戦略になります。
やったこと:3 層の設計
今回の設計は 3 層です。
1. 設計層(何を守るか)
-
SKILL-AUTHORING.md:スキル設計の 5 原則
- 1責務
- description でルーティング(読み手=Agent前提)
- Compact 優先
- 手続き(how)より判断(what/when)中心
- 完了条件を明示
- SKILL-INDEX.md:フェーズ別に「遅延読み込み」するルーティングマップ
2. ゲート層(どう守るか)
-
skill-quality-check.yml:PR 時の自動チェック(D-1)
- Check 1〜3:機械的に判定できるもの(frontmatter、行数、構造など)
- Check 4〜5:将来 LLM 判定にしたいが、まずは段階導入(現時点は手動レビューで代替)
3. 検証層(本当に効くか)
-
D-2:Before/After の比較(初回のリファクタ時のみ)
- ただし この記事時点では未実施です
- まず D-1 の運用を回し、スキルを 1 本ずつリファクタしたタイミングで測る予定です
正直、D-2 まできっちりやって初めて「効いた」と言えるのですが、今回は「壊れにくい運用の土台」を先に作った、というフェーズです。
フェーズ別遅延読み込み(SKILL-INDEX)
Agent が最初に読むのは SKILL-INDEX.md だけにして、必要なスキルだけを遅延読み込みします。
| フェーズ | 目的 | 同時参照の目安 |
|---|---|---|
| collect(収集) | 外部/内部から材料を集める | 2 |
| analyze(分析) | 差分検出・要約・根拠抽出 | 2〜3 |
| output(出力) | レポート生成・通知・PR化 | 2〜3 |
期待効果としては、最初に全部読む(~22,600 tokens)よりも、タスク単位で 5,000〜8,000 tokens 程度まで落とせる想定です(あくまで概算)。
独自の工夫:Load when / Avoid when
GitHub 公式の Agentic Workflows リポジトリ(github/gh-aw)を眺めると、スキルの「いつ読むべきか」を強く意識した書き方がありました。
そこで私たちは、各スキルに Load when(いつ読むか)を揃えたうえで、独自に Avoid when(いつ読まないか)も追加しました。
ポイントは「文章のうまさ」ではなく、定型ブロックで書式を固定することです。Agent にとってパースしやすくなります。
web-fetcher(例)
- Phase: collect
-
Load when
- URL からコンテンツを取得し Markdown に変換する必要があるとき
- 複数 URL の並列取得が必要な場合
-
Avoid when
- 既にローカルにデータがある場合
- Estimated tokens: ~800
「Avoid when」は効くのか?
これは論文に直接ある主張ではなく、私の仮説です。
スキル選択ミスの多くは「読まなくていいものを読んで混乱する」パターンなので、使う条件だけでなく、使わない条件も固定化すると誤選択が減るのでは、という狙いです。
開発プロセス:人間 × GPT × Copilot
タイムライン(約 30 分)
| 時刻 | アクター | やったこと |
|---|---|---|
| 13:28 | Copilot agent | Issue #76 を受けて initial plan 作成 |
| 13:36 | Copilot agent | ADR-002 / SKILL-AUTHORING.md / SKILL-INDEX.md / skill-quality-check.yml を一括生成 |
| 13:38 | Copilot agent | shellcheck warnings を自走修正 |
| 13:40 | 人間 | GPT にレビュー観点を出させる |
| 13:45 | 人間 | GPT 観点 × 実ファイルを突き合わせ、改善コメント(M1〜M4)を PR に投稿 |
| 13:50 | Copilot agent | M1〜M4 を反映(フェーズ分類、Load/Avoid、fetch-depth、運用設定追記) |
| 13:56 | Copilot agent | 具体例とガイダンスを追加・修正 |
※人間が書いたコードは 0 行です(判断とレビューはしています)。
3 者の役割分担
| アクター | 役割 | 具体的にやったこと |
|---|---|---|
| 人間 | 設計判断・レビュー観点の選定 | Issue 起票、GPT 出力の取捨選択、PR にレビューコメント |
| GPT | 構造化されたレビュー観点の生成 | 4 観点(R1〜R4)で抜け漏れ検出、失敗パターン提示 |
| Copilot agent | 生成・修正の実行 | ファイル生成、指摘反映、CI 破綻要因の修正 |
なぜ GPT をレビューに使ったのか
Copilot agent は「言われたことを実装する」のは得意ですが、設計意図からのズレを自分で検出するのは苦手です。
一方 GPT は「因果を分解してレビュー観点を列挙する」のが得意です。
実際、GPT の観点で PR を見たことで、次のような見落としを潰せました。
- checkout の
fetch-depth未指定で、origin/main...HEADの diff が失敗する可能性(CI 破綻)(R3) - Issue で決めたフェーズ分類が Index に反映されていない(ルーティングが弱い)(R2)
- Required check の設定導線が ADR に無い(運用上、形骸化し得る)(R3)
- Check 4/5(LLM 判定)が placeholder であることが明記されていない(誤解リスク)(R4)
迷った点(判断の痕跡)
最初、Copilot agent は SKILL-INDEX を「カテゴリ分類(データ収集/分析/通知...)」でまとめてきました。
一見わかりやすいのですが、私たちが狙っていたのは「collect → analyze → output」の 作業フェーズで遅延読み込みする設計です。
そこで人間側の判断として、
- 「カテゴリ分類は残してもいいが、フェーズ分類を第一にする」
- 「Agent の選択ミスを減らすために、Load when/Avoid when を定型化する」
という方向に寄せました。
このあたりは、出力をそのまま採用するのではなく「設計判断」を人間が持つべき部分でした。
学び
1. 「チェックリスト運用は破綻する」を前提に設計する
チェックリストは増えるほど見られなくなり、忙しくなるとスキップされます。
対策は CI でゲートにすることです。
- Check 1〜3:機械判定で強制
- Check 4〜5:いきなり自動 fail にせず、段階導入(手動レビュー → 将来 LLM 判定)
2. 段階導入が強い
最初から厳格にしすぎると運用が折れます。
- 行数超過は warning に留める(最初は fail にしない)
- LLM 判定は placeholder + 手動レビューで代替し、後で自動化する
厳しくするのは、運用が回り始めてからのほうが現実的です。
3. Agent への指示は「フォーマットを固定する」と壊れにくい
文章は揺れますが、構造は揺れません。
- Phase / Load when / Avoid when / Skill file / Estimated tokens
- Load when は最大 3、Avoid when は 1、などの制約も含めて固定
この「固定」が、エージェント運用の安定性に直結します。
4. 人間の仕事は「何を作るか」ではなく「何をレビューするか」
今回、人間が価値を出したのはコードではなく、
- どの設計判断を採用するか
- どの観点でレビューするか
- どこを段階導入にするか
の選定でした。
判断と選定に集中できるのは、エージェント開発の良さだと感じました。
次のステップ
- PR #77 を最終確認して merge
-
skill-quality-checkを Required status check に設定 - 既存 8 スキルをリファクタ(まず 1 本だけ模範例を作ってから横展開)
- D-2(Before/After)を初回リファクタのタイミングで実施(タスク完了率・トークン消費など)
後編予告
後編では、8 スキルのリファクタ結果と、D-2 の Before/After(タスク完了率・トークン消費など) をまとめます。
参考
- SkillsBench(arXiv:2602.12670)
- PR #77(ADR-002 + skill-quality-check)
- github/gh-aw(GitHub の Agentic Workflows 参考リポジトリ)