Communitygithub.com

aetox-skills/create-agent

スコープファーストなエージェント設計スキル — 境界を明確にしてからエージェントを作成します。

create-agent とは?

このスキルは、AIエージェントを設計する際に「スコープ(範囲)を最初に明確にする」という規律を強制します。プロンプト、設定ファイル、ツールバインディングを作成する前に、構造化されたスコープインタビューを実施し、エージェントの複雑さに応じた深さで要件を検証します。プロンプト作成スキルではなく、スコープ検証スキルであり、出力は検証済みの「エージェント仕様(Agent Spec)」— 別のAIや人間がエージェントを正しく構築するための設計図です。アーキタイプ(役割類型)、深さレイヤー(Quick/Standard/Deep/Critical)のシステムを備え、コードベースから情報を推測し、最小限の往復でユーザーと合意を形成します。Claude Code、Cursor、Codexなどの開発ツール上で動作し、アーキタイプに応じて質問するドメインを最適化するミニマイズリストを提供します。

対応✓Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add aetox-skills/create-agent

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

エージェント作成

目的

スコープファーストの規律でAIエージェントを設計します。プロンプト、設定、ツールバインディングを記述する前に、構造化されたスコープインタビューを必ず通過する必要があります。インタビューの深さは、設計するエージェントの複雑さに依存します。

これはプロンプト作成スキルではありません。スコープ検証スキルです。出力は検証済みのエージェント仕様(Agent Spec) — 別のAIや人間がエージェントを正しく構築するための設計図です。

すべてのエージェント仕様は8つの次元を定義します:

アーキタイプ → パーソナリティ → 機能 → I/O → エコシステム → メモリ → ライフサイクル → リスク/メトリクス

鉄のルール

  1. 構築前にスコープ — スコープが検証されるまで、コード、プロンプト、ツール設定は一切不可。例外はゼロ。

    修正権限: ドラフト/仕様の前提のみに適用 — ユーザーが見逃した前提(依存関係の欠落、矛盾、安全上のリスク)は、事前に尋ねずに修正して構いません。何をなぜ調整したかだけ説明してください。 承認なしに実際のファイル、設定、ツール、またはワークフローを変更してはいけません。 正しい解決策に新しいツールや既存のワークフローの変更が必要な場合は、事前に承認を求めてください — ただし、常識的に仕様を修正できる場合は、そのまま実行してください。

  2. 最小十分深度 — デフォルトはQuick。明示的なシグナルがある場合のみ、Standard/Deep/Criticalに昇格。Standardから始めないでください。

  3. まず推測、後で質問 — 質問する前に、コンテキスト、コードベース、既存のエージェント、およびユーザーが既に述べたことから答えを推測してみてください。本当に不確かなことだけを質問してください。

  4. コードベース優先 — 質問の答えが設定、ドキュメント、または既存のエージェントに存在する場合は、それを見つけてください。質問しないでください。 グリーンフィールド例外: コードベースが存在しない場合(index.md、AGENTS.md、opencode.jsonc、または既存のエージェントがない場合)、コードベーススキャンをスキップし、直接インタビューに進んでください。

  5. 往復を最小化 — 仕様を推測 → ドラフトを提示 → ユーザーに修正を許可。ドラフトで解決できない真のギャップについてのみ、一度に一つ質問してください。10個の質問を一度に投げかけないでください。

  6. 推奨、自由回答は避ける — すべての質問には推奨される答えを含めてください。反応できるものを提供してください。

  7. 仕様は承認必須 — エージェント仕様が明示的に承認されるまで、決して構築しないでください。Quickレイヤーの場合、推測された仕様に対するユーザーの確認が承認とみなされます。ステータス: Quick経由で承認済みとして文書化してください。

  8. シグナルで停止 — ユーザーが「十分」「停止」と言ったら、停止してください。議論したり、さらに進めようとしないでください。

  9. エージェント仕様を出力 — すべてのセッションは、Quickレイヤーであっても、検証済みの仕様を生成します。


エージェントアーキタイプシステム

エージェントはアーキタイプに基づいてパターンに従います。この表を使用して適切なアーキタイプを選択し、どのインタビュードメインに焦点を当てるか、またはスキップするかを理解してください。

アーキタイプカタログ

#アーキタイプコア目的デフォルトパーソナリティ典型的なツール推奨レイヤー
🛠️システム自動化、設定、保守実用的、簡潔、直接的CLI、ファイルシステム、Docker、gitQuick → Standard
🎨クリエイティブデザイン、ビジュアル、モーション表現力豊か、細部重視Tailwind、GSAP、画像APIQuick → Standard
💻開発者コード、アーキテクチャ、デバッグ技術的、正確、徹底的MCP、リンター、テストランナーQuick → Deep
📝スクライブ文書化、執筆、整理明確、構造化、忍耐強いObsidian、markdown、検索Quick
🔬スペシャリスト深い単一ドメイン権威的、綿密ドメイン固有CLI/MCPQuick → 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 + リスクモデル + コストモデル + セーフティゲート)

レイヤー選択

シグナルQuickStandardDeepCritical
エージェントが新規または変更(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ページのドラフトをユーザーに提示
  2. ユーザーが読んで修正(編集/追加/削除)
  3. 以下のチェックリストを使用して何が欠けているかを確認 — ドラフトがカバーしていないことだけを質問
  4. アーキタイプミニマイズリストを適用 — アーキタイプに応じて簡潔/自明ならスキップ/深掘り

チェックリストを順番に一つずつ質問しないでください — 最初にドラフトを提示し、ギャップについてのみ質問してください。

ドメイン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の全文が翻訳されます。上記は主要部分の翻訳例です。

関連スキル