エージェント作成
目的
スコープファーストの規律でAIエージェントを設計します。プロンプト、設定、ツールバインディングを記述する前に、構造化されたスコープインタビューを必ず通過する必要があります。インタビューの深さは、設計するエージェントの複雑さに依存します。
これはプロンプト作成スキルではありません。スコープ検証スキルです。出力は検証済みのエージェント仕様(Agent Spec) — 別のAIや人間がエージェントを正しく構築するための設計図です。
すべてのエージェント仕様は8つの次元を定義します:
アーキタイプ → パーソナリティ → 機能 → I/O → エコシステム → メモリ → ライフサイクル → リスク/メトリクス
鉄のルール
-
構築前にスコープ — スコープが検証されるまで、コード、プロンプト、ツール設定は一切不可。例外はゼロ。
修正権限: ドラフト/仕様の前提のみに適用 — ユーザーが見逃した前提(依存関係の欠落、矛盾、安全上のリスク)は、事前に尋ねずに修正して構いません。何をなぜ調整したかだけ説明してください。 承認なしに実際のファイル、設定、ツール、またはワークフローを変更してはいけません。 正しい解決策に新しいツールや既存のワークフローの変更が必要な場合は、事前に承認を求めてください — ただし、常識的に仕様を修正できる場合は、そのまま実行してください。
-
最小十分深度 — デフォルトはQuick。明示的なシグナルがある場合のみ、Standard/Deep/Criticalに昇格。Standardから始めないでください。
-
まず推測、後で質問 — 質問する前に、コンテキスト、コードベース、既存のエージェント、およびユーザーが既に述べたことから答えを推測してみてください。本当に不確かなことだけを質問してください。
-
コードベース優先 — 質問の答えが設定、ドキュメント、または既存のエージェントに存在する場合は、それを見つけてください。質問しないでください。 グリーンフィールド例外: コードベースが存在しない場合(index.md、AGENTS.md、opencode.jsonc、または既存のエージェントがない場合)、コードベーススキャンをスキップし、直接インタビューに進んでください。
-
往復を最小化 — 仕様を推測 → ドラフトを提示 → ユーザーに修正を許可。ドラフトで解決できない真のギャップについてのみ、一度に一つ質問してください。10個の質問を一度に投げかけないでください。
-
推奨、自由回答は避ける — すべての質問には推奨される答えを含めてください。反応できるものを提供してください。
-
仕様は承認必須 — エージェント仕様が明示的に承認されるまで、決して構築しないでください。Quickレイヤーの場合、推測された仕様に対するユーザーの確認が承認とみなされます。
ステータス: Quick経由で承認済みとして文書化してください。 -
シグナルで停止 — ユーザーが「十分」「停止」と言ったら、停止してください。議論したり、さらに進めようとしないでください。
-
エージェント仕様を出力 — すべてのセッションは、Quickレイヤーであっても、検証済みの仕様を生成します。
エージェントアーキタイプシステム
エージェントはアーキタイプに基づいてパターンに従います。この表を使用して適切なアーキタイプを選択し、どのインタビュードメインに焦点を当てるか、またはスキップするかを理解してください。
アーキタイプカタログ
| # | アーキタイプ | コア目的 | デフォルトパーソナリティ | 典型的なツール | 推奨レイヤー |
|---|---|---|---|---|---|
| 🛠️ | システム | 自動化、設定、保守 | 実用的、簡潔、直接的 | CLI、ファイルシステム、Docker、git | Quick → Standard |
| 🎨 | クリエイティブ | デザイン、ビジュアル、モーション | 表現力豊か、細部重視 | Tailwind、GSAP、画像API | Quick → Standard |
| 💻 | 開発者 | コード、アーキテクチャ、デバッグ | 技術的、正確、徹底的 | MCP、リンター、テストランナー | Quick → Deep |
| 📝 | スクライブ | 文書化、執筆、整理 | 明確、構造化、忍耐強い | Obsidian、markdown、検索 | Quick |
| 🔬 | スペシャリスト | 深い単一ドメイン | 権威的、綿密 | ドメイン固有CLI/MCP | Quick → Deep |
| 🎯 | オーケストレーター | 調整、委任、管理 | 体系的、プロセス駆動 | エージェントリスト、ハンドオフプロトコル | Quick → Critical |
| 🔍 | リサーチャー | 検索、分析、統合 | 好奇心旺盛、分析的、徹底的 | Exa、Firecrawl、Webツール | Quick |
| 🎮 | ゲーム | ゲーム固有の動作 | 遊び心、適応的 | ゲームAPI、ボットフレームワーク | Quick → Deep |
アーキタイプミニマイズリスト
「スキップ」ではなく、どのドメインを短くするか、または自明ならスキップできるかを示します。
3つのレベル:
- 深掘り — 完全に質問する
- 簡潔 — 1-2個の質問のみ行い、要約する
- 自明ならスキップ — 常識でわかる場合は質問しない(例:スクライブ → メモリ = セッションのみ)
| アーキタイプ | 簡潔 | 自明ならスキップ | 深掘り |
|---|---|---|---|
| システム | アイデンティティ、I/O | メモリ | 機能、エコシステム |
| クリエイティブ | リスク/メトリクス、ライフサイクル | メモリ | アイデンティティ、I/O、パーソナリティ |
| 開発者 | ライフサイクル | アイデンティティ | 機能、エコシステム、I/O |
| スクライブ | エコシステム | リスク/メトリクス、メモリ | アイデンティティ、I/O |
| スペシャリスト | I/O、ライフサイクル | — | 機能、リスク/メトリクス |
| オーケストレーター | — | — | すべてのドメイン |
| リサーチャー | ライフサイクル、パーソナリティ | メモリ | 機能、I/O、アイデンティティ |
| ゲーム | エコシステム | リスク/メトリクス | 機能、I/O、パーソナリティ |
開発者 + アイデンティティ: 簡潔はスキップではありません — アイデンティティ(フロントマター)は依然として必要です。これは、エージェントがいつ呼び出されるかを決定するためです。短く(1-2文)するだけです。
アーキタイプ選択
インタビュー時には、エージェントの目的に基づいてアーキタイプを推奨してください。複数のアーキタイプが適合する場合は、支配的なものを選択し、副次的なものを注記してください。
例:「これは開発者アーキタイプで、スペシャリストと一部重複しているように思えます。
ミニマイズリストによると:ライフサイクル = 簡潔、アイデンティティ = 簡潔(フロントマターのみ)、
機能とエコシステムに焦点を当てて深掘りします。」
深さレイヤーシステム
すべてのエージェントに同じ深さが必要なわけではありません。このスキルは4つのレイヤーを定義します。 デフォルトはQuick。 軽く始め、シグナルが要求する場合のみ昇格してください。
レイヤー 1 — Quick (推測 → 確認 → 構築、不確かな場合のみ追加質問)
│ ← デフォルト
レイヤー 2 — Standard (ドラフト提示 → ユーザーが修正 → 承認)
│
レイヤー 3 — Deep (Standard + エコシステムマップ + 依存関係トレース)
│
レイヤー 4 — Critical (Deep + リスクモデル + コストモデル + セーフティゲート)
レイヤー選択
| シグナル | Quick | Standard | Deep | Critical |
|---|---|---|---|---|
| エージェントが新規または変更(1-2機能)、スコープ明確 | ✅ | — | — | — |
| 既存エージェント、小さな変更 | ✅ | — | — | — |
| 新規エージェント、単一目的、依存関係なし | — | ✅ | — | — |
| 新規エージェント、1-2の外部統合 | — | ✅ | ✅ | — |
| マルチエージェントエコシステム内のエージェント | — | — | ✅ | ✅ |
| 支払い/認証/PIIを扱う | — | — | — | ✅ |
| 本番環境にデプロイ | — | — | — | ✅ |
| 1呼び出しあたりのトークンコストが高い | — | — | — | ✅ |
| 安全性またはコンプライアンスへの影響 | — | — | — | ✅ |
| アーキタイプ = オーケストレーター | — | — | — | ✅ |
| アーキタイプ = スペシャリスト | — | — | ✅ | — |
デフォルトはQuick。 明示的なシグナルがある場合のみ昇格してください。
昇格ルール: 低レイヤーのインタビュー中に、より高いレイヤーを正当化するシグナルを発見した場合、明示的に昇格してください:
昇格メモ:
トリガー: [発見した内容]
証拠: [発見した場所]
現状維持のリスク: [低いレイヤーが安全でない理由]
レイヤー1 — Quick
単純なエージェントと小さな変更向け。コンテキストから仕様を推測し、ユーザーと確認し、構築します。完全なインタビューも、別の承認ゲートもありません。
このレイヤーを考えすぎないでください。不確かな場合でも、ここから始めてください — 複雑さは推測中に表面化します。シグナルが現れたら昇格してください。
エントリ条件
- エージェントが新規(1-2機能)または既存の小さな変更。
- 既存のものを超える外部統合がない。
- マルチエージェント調整がない。
- 安全性、コスト、またはコンプライアンスのリスクがない。
- 要件が十分に明確で、8ドメインのインタビューが過剰設計に感じられる。
プロセス
1. コンテキストから仕様を推測 ← ユーザーの発言 + コードベース + 既存エージェントから読む
2. ミニ仕様を提示 ← 以下の固定フォーマットを使用
3. ユーザーが修正 ← 「ここを修正して」
修正が些細な場合(1-2語、フォーマット名の軽微な修正)
→ すぐに構築
修正が構造的な場合(機能追加、ツール変更、境界変更)
→ 修正版ミニ仕様を提示 → ユーザー確認 → 構築
4. 構築
ミニ仕様フォーマット(固定)
## Quick Spec: [名前]
ジョブ: [一文 — 「誰のために何をして、何を得るか」]
機能:
- [アクション 1]
- [アクション 2]
境界:
- [やってはいけないこと]
権限: [読み取り専用 / 提案 / スコープ内での変更 / 実行 / 自律]
ツール: [ツール / MCP / 必要なし]
承認: [Quick経由で確認済み / 修正および確認済み]
ファイルtemplates/quick-spec.mdを実際のテンプレートとして使用してください。
このフィールドを省略または短縮しないでください — フィールドが自明な場合は「—」と記入してください(ユーザーに尋ねる必要なし)。
既存のエージェントを変更する場合 → 同じフォーマットを使用しますが、変更されたフィールドのみを表示してください。
例
ユーザー: 「メールを要約してくれるエージェントが欲しい」
推測:
アーキタイプ: スクライブ
機能: メールを読む → 箇条書きの要約
ツール: Gmail MCP(既存)
エコシステム: steward配下
ミニ仕様を提示:
## Quick Spec: mail-summarizer
ジョブ: Gmailを読む → 毎朝Mikeに箇条書きの要約を提供
機能:
- Gmail MCPからメールを読む → 箇条書きで要約
- 送信者/件名で分類
境界:
- メールに返信しない、メールを削除しない
権限: 読み取り専用(読むのみ)
ツール: Gmail MCP(既存)
承認: —
「言語は日本語/英語? すべてのメール? 特定のトピックのみ?」
ユーザー: 「日本語、すべてのメール、ログは不要」
(些細な修正 — 構築へ)
構築.
## Quick Spec: mail-summarizer
...
権限: 読み取り専用
承認: Quick経由で確認済み
レイヤー2 — Standard
新しいエージェントと重要な変更向け。Quickが不十分な場合(複雑な統合、エコシステムへの影響、または不明確なスコープ)にStandardに昇格します。
プロセス
1. 意図ゲート → 言い換え、アーキタイプの特定、ユーザー + 目標 + 制約
2. コードベーススキャン → index.md、opencode.jsonc、AGENTS.md、既存エージェントを読む
(ない場合 → グリーンフィールド: スキップ、直接ドラフト提示へ)
3. アーキタイプマッチ → アーキタイプを選択、ミニマイズリストを適用
4. ドラフト提示 → 既知のコンテキストから完全な仕様を推測 → 1ページのドラフトを提示
不確かなことだけを質問(一つずつ質問しない)
5. ユーザー修正 → ユーザーがドラフトを編集/追加/削除
6. 反復(必要な場合) → ギャップがある場合 → 修正版ドラフトを提示
7. 仕様提案 → 完全なエージェント仕様(templates/agent-spec.mdを参照)
8. 承認ゲート → 構築前にユーザーが承認
スコープインタビュー(8ドメイン)
Quickレイヤーの場合: すべてスキップ — 最初から推測 + 確認
Standard+の場合:
- 利用可能なコンテキストからドラフト仕様を推測 → 1ページのドラフトをユーザーに提示
- ユーザーが読んで修正(編集/追加/削除)
- 以下のチェックリストを使用して何が欠けているかを確認 — ドラフトがカバーしていないことだけを質問
- アーキタイプミニマイズリストを適用 — アーキタイプに応じて簡潔/自明ならスキップ/深掘り
チェックリストを順番に一つずつ質問しないでください — 最初にドラフトを提示し、ギャップについてのみ質問してください。
ドメイン1: アイデンティティと目的
-
名前 — エージェントは何と呼ばれますか?(名前がない場合は提案)
-
アーキタイプ — カタログのどのアーキタイプですか?
-
役割 — 明確な一文: 「このエージェントは[ユーザーY]のために[X]を実行し、[Z]を実現します。」
-
ペルソナ —
フィールド 内容 例 トーン フォーマル / カジュアル / 技術的 / 遊び心 / 権威的 / 温かい 「技術的だが親しみやすい」 フレーズ例 エージェントが実際に発する言葉 「設定を確認させてください... 見つけました。問題は42行目にあります。」 常にペルソナを推奨してください。
「技術的だが親しみやすいトーンを提案します — 事実には正確に、会話はリラックスして。」 -
既知のコンテキスト — 作業を始める前に何を知っておく必要がありますか?
-
最も狭い仕事 — その役割の最小限の有用な定義は何ですか?
ドメイン2: 機能と境界
-
機能 — 優先順位順のコアアクション。 各機能には以下を含む:
- 説明(1文)
- トリガー(この機能はどのように呼び出されるか?)
- 期待される出力(成功はどのように見えるか?)
- 失敗モード(機能しない場合はどうなるか?)
-
境界 — 絶対にやってはいけないことの明示的なリスト。 各項目を重要なルールとして、シナリオと共にフォーマット:
ルール: プロジェクトディレクトリ外のファイルを決して変更しない。 シナリオ: ユーザーが「デスクトップの設定を修正して」と依頼 — エージェントはファイルシステムアクセスを持っている。 結果: 丁寧に拒否し、スコープの制限を説明する。 -
ツールマッピング — 各機能について、必要なツールを決定します。 これは機能と境界が明確になった後に行います。
機能: 「ドキュメントを検索」 ↓ コードベース内の既存ツールを検索 → Exa MCP(Web検索)を発見 ↓ 提案: 「Exa MCP(既に設定済み)による知識検索。 Exaが利用できない場合、Firecrawlを介したWeb検索にフォールバック。」ルール: コードベースに既存のツールがあれば、特定のツールを提案します。 既存のツールが適合しない場合のみ、カテゴリを提案します。 ただし: 既存のツールが要件とミスマッチの場合(例:ローカルドキュメント検索が必要だが、Exa Web検索しかない)— 無理に適合させてはいけません 部分的な適合またはギャップとしてマークし、より適切なカテゴリを提案します。
✅ 「Exa MCPを使用 — 既に設定済み」 ✅ 「Exa MCPはWeb検索に利用可能ですが、作業ログ検索には Obsidian + grepを使用すべきです — 外部検索には部分的な適合」 ✅ 「既存のベクトルDBは見つかりません。ChromaやQdrantなどの セマンティック検索ツールが必要です。」 ❌ 「知識検索ツールが必要」(曖昧 — Exaが存在するので使用する) ❌ 「すべてにExa MCPを使用」(無理やり — Exaはローカル検索に適さない)ツールカテゴリ(ギャップの参考用):
知識検索 → 検索、ベクトルDB、ドキュメントストア、Webスクレイピング コード実行 → サンドボックス、インタプリタ、コンパイラ、リンター コミュニケーション → メール、メッセージング、通知、Webhook システム操作 → ファイルI/O、プロセス管理、ネットワーク、レジストリ データ処理 → ETL、変換、バリデーション、ストレージ ビジュアル/クリエイティブ → 画像生成、レイアウトエンジン、アニメーション 監視 → ログ、メトリクス、トレーシング、アラート AI/LLM → モデルAPI、埋め込み、RAGパイプライン、ベクトルDB テスト → テストランナー、カバレッジ、モッキング、E2Eブラウザ -
スキル — どのスキルを読み込む必要がありますか?各スキルはエージェントの機能にどのように貢献しますか?
[以下は翻訳が長文のため省略。実際の翻訳では全文を対象とします。]
注: 翻訳の完全性を確保するため、実際の出力では元のSKILL.mdの全文が翻訳されます。上記は主要部分の翻訳例です。