長いプロンプトから業務マニュアルへ——Agent Skillsの設計

Executive Summary

Agentへ詳しい指示を与えるために、毎回すべての規則を長いPromptへ入れる方法には限界があります。仕事が増えるほどPromptは膨らみ、関係のない規則が混ざり、重要な条件が埋もれるからです。

Agent Skillは、単なる「保存した長文Prompt」ではありません。

いつ使うかを示すmetadata、どう進めるかを示す手順、何を出すかを示す出力契約をまとめた、選択可能な業務単位です。普段は小さな目次だけを参照し、依頼に合ったSkillの本文だけを読み込むProgressive Disclosureによって、文脈を必要以上に膨らませず専門化できます。

本稿では、Lab 1のcode-review Skillを使い、次を順に説明します。

• Static ContextとDynamic Contextの違い
• SKILL.mdが「業務契約」である理由
• metadataからSkill実行までの公開可能な流れ
• Skillを増やすときに起こる4種類の失敗
• 1 Agent＋SkillsとMulti-agentをどう使い分けるか

シリーズの現在地

全5回で「AIがものすごく賢くなった。では、本当に仕事を任せられるのか？」を追っています。

1. Agentic Engineeringとは何か
2. Antigravityという職場
3. Agent Skillsという業務マニュアル（今回）
4. Agents CLIとADK Graphによる工程設計
5. OutputとTrajectoryによる評価

前回からの接続——職場の規則と、仕事の手順は違う

前回は、AntigravityをAgentの職場として読みました。Projectが案件の境界を作り、MCPが外部への接続面を作り、Permissionsが操作範囲を制限し、Artifactsが人間の検査を支えます。

しかし、職場を用意しても、新人はコードレビューの進め方を知りません。

「正確に」「安全に」といった共通規則だけでは、どのファイルを調べ、何を優先し、どんな形式で指摘するかが曖昧です。個別業務には、その仕事固有の手順が要ります。

つまり、Projectの共通規則が就業規則なら、Skillは特定業務のマニュアルです。

毎朝、全マニュアルを読み上げる会社

新人へ仕事を頼むたびに、次の内容を全部読み上げる会社を想像してください。

• 会社の基本方針
• コードレビュー手順
• デプロイ手順
• 障害対応手順
• セキュリティ監査手順
• 月次レポート手順
• 採用面接手順

今日の依頼がコードレビューだけでも、全マニュアルを聞かされます。時間がかかるだけでなく、「今回は何が重要か」も見えにくくなります。手順同士が矛盾すれば、どちらを優先するかも曖昧です。

AIのContext windowへ大量の指示を常時入れる場合も、同じ問題が起きます。

そこで情報を二つに分けます。

Static Context——机の上へ常に置くもの

どの仕事でも必要な、少量の情報です。

• Agentの役割と目的
• 会社全体の禁止事項
• Projectの構成や共通規約
• 利用できるSkillの短い目次

常に参照できるため確実ですが、多すぎるとContextを占有します。

Dynamic Context——必要なときだけ書棚から出すもの

特定の仕事が選ばれた後に読む、詳しい情報です。

• コードレビューの確認項目
• デプロイ前のチェックリスト
• 障害対応の切り分け手順
• 業務別のテンプレートや補助スクリプト

こちらは必要なときだけ読み込めるため、専門的な手順を増やしやすくなります。

この「目次は小さく常駐し、本文は選択後に読む」という段階的な開示をProgressive Disclosureと呼びます。

つまり、Contextを賢くする方法は、全部を渡すことではなく、必要な情報へ必要な時点で到達できるようにすることです。

SKILL.mdは何を契約するのか

Build With Google Day 1 Lab 1では、Project内に次の構造でCustom Skillを作ります。

my-first-project/
└─ .agents/
   └─ skills/
      └─ code-review/
         └─ SKILL.md

LabのSKILL.mdは、大きく二層に分かれます。

---
name: code-review
description: Reviews code changes for bugs, style issues, and best practices.
             Use when reviewing code files or checking programming quality.
---

〈Code Review Skill〉

## Review Checklist
1. Correctness
2. Edge Cases
3. Performance

## Feedback Protocol
- 行番号と、変更すべき箇所を示す
- 修正の技術的な理由を説明する

最初のYAML部分がmetadataです。nameはSkillの識別名、descriptionは「どんな依頼で候補になるか」を伝えます。

本文は実行契約です。何を調べるか、どんな順で進むか、何を出力するかを定義します。

ここでdescriptionを単なる紹介文と考えないことが重要です。

弱いdescription
  「コードを扱うSkillです」
  → 対象が広すぎ、いつ使うのか分からない

強いdescription
  「コードファイルのレビューや品質確認を依頼されたときに使い、
    bug・edge case・performanceを調べる」
  → 適用条件と仕事の範囲が分かる

実務では非適用条件も有効です。「新機能の実装には使わない」「ファイルを変更せずレビューコメントだけを返す」のように、境界を明示すると隣のSkillとの衝突を減らせます。

つまり、SKILL.mdは知識のメモではなく、選択条件・実行手順・出力形式を結ぶ業務契約です。

Skillはどう選ばれ、どう使われるのか

外から説明可能な範囲を、次の図に整理しました。

1. ユーザーが「このPythonをレビューして」と依頼する。
2. Agent側が、利用可能なSkillの小さなmetadataと依頼を照合する。
3. code-reviewが候補として選ばれる。
4. 選ばれた後にSKILL.mdの本文を読む。
5. Checklistを実行し、Feedback Protocolに沿って出力する。

選ばれなかったデプロイや障害対応の本文は、この依頼のContextへ入れる必要がありません。これがProgressive Disclosureの実益です。

ただし、この図はAgent Skillsの契約モデルです。特定製品の非公開routerが、内部でまったく同じアルゴリズムを実装していると主張するものではありません。

つまり、私たちが設計・検査できるのは「どのmetadataを公開し、選択後に何を実行させるか」であり、見えない内部処理を想像する必要はありません。

VM上で確認したcode-review Skill

VM上では、Project-localなcode-review Skillについて、次を確認しました。

• nameとdescriptionを持つ
• Correctness、Edge Cases、Performanceを確認する
• 行番号を示す
• 問題の理由と修正方針を説明する

さらにLabのdemo_bad_code.pyに対するレビューでは、次の二点が可視の結果として示されました。

1. get_user_data(...)がNoneを返し得るのに、戻り値を検査せずu['name']へ進むcrash path。
2. 支払い処理のloop内にあるtime.sleep(0.1)が、処理を直列に待たせるperformance bottleneck。

これはSkill契約との対応が明確です。

ここから言えるのは、ProjectにSkillが登録され、その一例の出力が契約した観点と対応したことです。一回の成功から、すべてのコードで正しくレビューできる、あるいは内部routerの選択精度が何％である、とまでは言えません。

つまり、Skillの価値は「賢そうな回答」ではなく、依頼、確認項目、出力が追跡可能な契約でつながることにあります。

Skill、共通ルール、MCPは何が違うのか

この三つは混同されやすいため、新人のたとえへ戻します。

コードレビューSkillが「静的解析Toolを呼ぶ」と指示することはできます。しかし、Skill自身が外部システムへの接続能力そのものではありません。

反対に、MCP Toolが使えても、いつ、どの順で、どんな結果を確認して使うかはSkillやWorkflow側の責務です。

つまり、共通ルールは常時の境界、Skillはオンデマンドの手順、MCPは外部への到達手段です。

Skillを増やせば増やすほどよいのか

答えは「いいえ」です。Skillは一つのAgentを専門化しますが、ライブラリ全体としては新しい失敗を持ち込みます。

Build With Googleの講演では、Skill評価の主な失敗を4種類に整理していました。

1. Trigger Failure

使うべきSkillが選ばれない、または関係ないSkillが選ばれます。

原因の例：descriptionが抽象的、隣接Skillと語彙が重なる、非適用条件がない。

2. Execution Failure

正しいSkillは選ばれたが、手順を飛ばす、Toolを誤る、出力形式を守らない状態です。

原因の例：手順が曖昧、成功条件がない、例外処理が記されていない。

3. Token Budget Failure

本文や参照資料が大きすぎて、重要な情報がContext内で埋もれます。

原因の例：必要時に読めばよい資料まで本文へ直書き、手順と背景説明の分離不足。

4. Regression

新しいSkillを追加した結果、既存Skillとの選択が競合し、以前動いていた依頼が壊れます。

原因の例：適用範囲の重複、Skill名やdescriptionの似すぎ、ライブラリ全体の回帰テスト不足。

Skill単体の品質
  ≠ Skill library全体の品質

単体で正しいSkill
  + 似たSkill
  → routing競合という新しいシステム問題

つまり、Skillは作って終わりではなく、「選ばれるか」「正しく実行するか」「文脈を圧迫しないか」「既存を壊さないか」を評価する必要があります。

Single Agent + Skills
  向く：同じ権限・同じ作業境界で、手順だけを切り替える仕事

Multi-agent
  向く：本当に並列実行したい、互いに独立評価したい、
        権限や実行環境を厳格に分離したい仕事

今回の持ち帰り

• Skillは保存した長文Promptではない。 metadata、実行手順、出力形式を結ぶ選択可能な業務契約。
• Progressive Disclosureは文脈の配置設計。 目次は常駐し、詳しい本文は選択後に読む。
• Skill libraryは評価が必要。 Trigger、Execution、Token Budget、Regressionの4面を見る。

次回へ

コードレビューのような一つの業務なら、Skillの手順で進められます。

では、問い合わせを分類し、配送の相談だけを専門担当へ送り、関係のない相談は丁寧に断る、といった複数工程はどうでしょうか。どの順番で進み、どの条件で分岐し、どこへは進ませないかを管理する必要があります。

次回は、Agents CLIとADK Graphを使い、LLMの曖昧な判断とコードの厳密な制御を分けます。

参考資料

• Build With Google Day 1 — Lab 1
• Agent Skills specification
• Adding Agent Skills support
• Skill authoring best practices
• Evaluating skills