Communitygithub.com

aetox-skills/create-agent

範圍優先的代理設計技能 — 先問清楚範圍,再建立代理。

create-agent 是什麼?

這是一個以「範圍優先」為核心紀律的 AI 代理設計技能。它強制在編寫任何提示詞、設定檔或工具繫結之前,先進行一次結構化的範圍訪談,訪談的深度會根據所設計代理的複雜度自動調整。此技能並非提示詞撰寫技能,而是範圍驗證技能;其產出是經過驗證的「代理規格書」(Agent Spec),這份藍圖可供其他 AI 或人類正確建構代理。技能定義了涵蓋 Archetype(原型)到 Risk/Metrics(風險/指標)等 8 個維度的規格,並提供 4 個深度層級(Quick、Standard、Deep、Critical),預設從最輕量的 Quick 層開始,僅在出現明確訊號時才會升級。本技能支援 Cursor、Claude Code、Codex 等主流 AI 代理平台,其特有的「原型系統」與「最小化清單」能確保訪談效率,避免不必要的來回問答。

相容平台✓Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add aetox-skills/create-agent

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

建立代理 (Create Agent)

目的

以範圍優先的紀律來設計 AI 代理。在編寫任何提示詞、設定檔或工具繫結之前,你必須通過一次結構化的範圍訪談。訪談的深度取決於所設計代理的複雜度。

這不是提示詞撰寫技能。這是一個範圍驗證技能。其產出是一份經過驗證的代理規格書 (Agent Spec) — 一份可供其他 AI 或人類正確建構代理的藍圖。

每個代理規格書定義了 8 個維度:

Archetype → Personality → Capabilities → I/O → Ecosystem → Memory → Lifecycle → Risk/Metrics

鐵則 (Iron Rules)

  1. 範圍優先,後建構 — 在範圍驗證之前,不得有任何程式碼、提示詞或工具設定。零例外。

    修正權限: 僅適用於草稿/規格假設 — 直接修正使用者在規格中遺漏的假設(如缺少的依賴、矛盾、安全風險),無需先提問。只需說明調整了什麼以及原因。 嚴禁在未經核准的情況下修改實際的檔案、設定、工具或工作流程。 若正確的解決方案需要更換新工具或變更現有工作流程,則需先請求核准 — 但如果是一般常識範圍內的規格修正,請直接處理。

  2. 最小足夠深度 — 預設為 Quick。僅在出現明確訊號時,才提升至 Standard/Deep/Critical。請勿從 Standard 開始。

  3. 先推論,後提問 — 在提問之前,先嘗試從上下文、程式碼庫、現有代理以及使用者已說的內容中推論答案。僅針對仍然不確定的部分提問。

  4. 程式碼庫優先 — 如果問題的答案存在於設定、文件或現有代理中,請直接查找。不要提問。 綠地例外: 如果沒有任何程式碼庫(沒有 index.md、AGENTS.md、opencode.jsonc 或現有代理),則跳過程式碼庫掃描,直接進入訪談。

  5. 最小化往返次數 — 推論規格 → 呈現草稿 → 讓使用者標記修正。僅針對草稿無法解決的真正缺口,才逐一提問。切勿一次傾倒 10 個問題。

  6. 提供建議,而非開放式問題 — 每個問題都必須包含一個建議答案。給出可以讓使用者回應的內容。

  7. 規格必須被核准 — 在「代理規格書」被明確核准之前,絕不開始建構。對於 Quick 層級,使用者對推論規格的確認即視為核准。將其記錄為 Status: Approved via Quick。

  8. 遇訊號即停止 — 當使用者說「夠了」或「停止」時,立即停止。不要爭論,不要強迫進一步。

  9. 輸出代理規格書 — 每個階段都應產出一份經過驗證的規格,即使是在 Quick 層級。


代理原型系統 (Agent Archetype System)

代理根據其原型遵循特定模式。使用此表格來選擇正確的原型,並了解應關注或跳過哪些訪談領域。

原型目錄 (Archetype Catalog)

#原型核心目的預設個性典型工具建議層級
🛠️系統 (System)自動化、設定、維護務實、簡潔、直接CLI, filesystem, Docker, gitQuick → Standard
🎨創意 (Creative)設計、視覺、動態富表現力、注重細節Tailwind, GSAP, image APIsQuick → Standard
💻開發者 (Developer)程式碼、架構、除錯技術性、精確、徹底MCPs, linters, test runnersQuick → Deep
📝抄寫員 (Scribe)文件、寫作、組織清晰、結構化、有耐心Obsidian, markdown, searchQuick
🔬專家 (Specialist)深入單一領域權威性、一絲不苟Domain-specific CLI/MCPQuick → Deep
🎯協調者 (Orchestrator)協調、委派、管理系統性、流程導向Agent list, handoff protocolQuick → Critical
🔍研究員 (Researcher)搜尋、分析、綜合好奇、分析性、徹底Exa, Firecrawl, web toolsQuick
🎮遊戲 (Game)遊戲特定行為好玩、適應性強Game API, bot frameworkQuick → Deep

原型最小化清單 (Archetype Minimize List)

這不是「跳過」,而是指出哪些領域應該簡短或明顯時可跳過。

共有 3 個等級:

  • 深入 (Deep-dive) — 完整提問
  • 簡短 (Brief) — 只問 1-2 個問題,然後總結
  • 明顯則跳過 (Skip if obvious) — 如果常識可以判斷,則不問(例如 Scribe → Memory = session-only)
原型簡短 (Brief)明顯則跳過 (Skip if obvious)深入 (Deep-dive)
系統 (System)Identity, I/OMemoryCapabilities, Ecosystem
創意 (Creative)Risk/Metrics, LifecycleMemoryIdentity, I/O, Personality
開發者 (Developer)LifecycleIdentityCapabilities, Ecosystem, I/O
抄寫員 (Scribe)EcosystemRisk/Metrics, MemoryIdentity, I/O
專家 (Specialist)I/O, Lifecycle—Capabilities, Risk/Metrics
協調者 (Orchestrator)——所有領域
研究員 (Researcher)Lifecycle, PersonalityMemoryCapabilities, I/O, Identity
遊戲 (Game)EcosystemRisk/MetricsCapabilities, I/O, Personality

開發者 + Identity: 簡短而非跳過 — identity (frontmatter) 仍然必須存在,因為它決定了代理何時被呼叫。只需保持簡短(1-2 句話)。

原型選擇 (Archetype Selection)

進行訪談時,根據代理的目的推薦一個原型。如果符合多個原型,請選擇主導原型並註明次要原型。

範例:「這聽起來像是一個開發者 (Developer) 原型,並帶有一些專家 (Specialist) 重疊。
        根據最小化清單:Lifecycle = 簡短, Identity = 簡短 (僅限 frontmatter),
        重點深入 Capabilities + Ecosystem。」

深度層級系統 (Depth Layer System)

並非每個代理都需要相同的深度。此技能定義了 4 個層級。 預設為 Quick。 從輕量開始,僅在出現訊號要求時才升級。

Layer 1 — Quick       (推論 → 確認 → 建構,不確定時才問)
                       │                          ← 預設值
Layer 2 — Standard    (呈現草稿 → 使用者標記 → 核准)
                       │
Layer 3 — Deep        (Standard + 生態系地圖 + 依賴追溯)
                       │
Layer 4 — Critical    (Deep + 風險模型 + 成本模型 + 安全閘門)

層級選擇 (Layer Selection)

訊號QuickStandardDeepCritical
代理是新的或已修改(1-2 個能力),範圍明確✅———
現有代理,小幅修改✅———
新代理,單一用途,無依賴—✅——
新代理,1-2 個外部整合—✅✅—
代理位於多代理生態系中——✅✅
處理支付 / 身分驗證 / PII———✅
部署至正式環境———✅
每次呼叫的高 Token 成本———✅
安全或合規影響———✅
原型 = 協調者 (Orchestrator)———✅
原型 = 專家 (Specialist)——✅—

預設為 Quick。 僅在出現明確訊號時才升級。

升級規則: 如果在較低層級的訪談中發現需要更高層級的訊號,請明確升級:

升級備註:
  觸發條件:[你發現的內容]
  證據:[你在哪裡發現的]
  停留的風險:[為什麼較低層級不安全]

第 1 層 — Quick

適用於簡單的代理和小型變更。從上下文推論規格,與使用者確認,然後建構。無需完整訪談,也無需單獨的核准關卡。

不要太過度思考這個層級。如果不確定,仍然從這裡開始 — 在推論過程中會浮現複雜性。如果出現訊號,再升級。

進入條件 (Entry Criteria)

  • 代理是新的(1-2 個能力)或現有代理經小幅修改。
  • 沒有超越現有內容的外部整合。
  • 沒有多代理協調。
  • 沒有安全、成本或合規風險。
  • 需求足夠清晰,以至於進行 8 個領域的訪談感覺像是過度設計。

流程 (Process)

1. 從上下文推論規格    ← 從使用者告知的內容 + 程式碼庫 + 現有代理中讀取
2. 呈現迷你規格          ← 使用下方固定格式
3. 使用者標記修正        ← 「哪裡需要修改請告知」
   如果標記是瑣碎的(1-2 個字,略微修正名稱格式)
     → 可以直接建構
   如果標記是結構性的(增加能力、更換工具、修改邊界)
     → 先呈現修正後的迷你規格 → 使用者確認 → 建構
4. 建構

迷你規格格式(固定)

## Quick Spec: [名稱]

Job: [一句話 — 「做什麼事、為了誰、得到什麼」]
Capabilities:
  - [動作 1]
  - [動作 2]
Boundaries:
  - [絕對不能做的事]
Authority: [Read-only / Suggest / Modify in scope / Execute / Autonomous]
Tools: [工具 / MCP / 不需要]
Approval: [Confirmed via Quick / Revised & Confirmed]

使用檔案 templates/quick-spec.md 作為實際範本。 嚴禁省略或跳過這些欄位 — 如果某個欄位很明顯,請寫「—」(無需詢問使用者)。 如果是修改現有代理 → 使用相同格式,但僅顯示有變更的欄位。

範例

使用者:「我想要一個代理幫我摘要郵件。」

推論:
  Archetype: Scribe
  Capability: 讀取郵件 → 重點摘要
  Tools: Gmail MCP (已存在)
  Ecosystem: 歸管理器 (steward) 管理

呈現迷你規格:
  ## Quick Spec: mail-summarizer

  Job: 讀取 Gmail → 每天早上為 Mike 產生重點摘要
  Capabilities:
    - 從 Gmail MCP 讀取郵件 → 摘要為重點列表
    - 根據寄件者 / 主旨分類
  Boundaries:
    - 嚴禁回覆郵件、嚴禁刪除郵件
  Authority: Read-only (唯讀)
  Tools: Gmail MCP (已存在)
  Approval: —

  「使用中文還是英文?全部郵件還是特定主題?」

使用者:「中文,全部郵件,不需要記錄。」
  (瑣碎標記 — 直接建構)

建構。
  ## Quick Spec: mail-summarizer
  ...
  Authority: Read-only
  Approval: Confirmed via Quick

第 2 層 — Standard

適用於新代理和重大變更。當 Quick 層級不足時(複雜整合、生態系影響或範圍不明確),升級至 Standard。

流程 (Process)

1. 意圖閘門       → 複述、識別原型、使用者 + 目標 + 限制
2. 程式碼庫掃描     → 讀取 index.md, opencode.jsonc, AGENTS.md, 現有代理
                       (如果沒有 → 綠地:跳過,直接呈現草稿)
3. 原型匹配   → 選擇原型,套用最小化清單
4. 呈現草稿     → 從已知上下文推論完整規格 → 呈現一頁草稿
                       僅針對不確定性提問(不要逐項詢問)
5. 使用者標記修正      → 使用者編輯 / 增加 / 從草稿中刪除
6. 疊代(如有需要) → 如果有缺口 → 呈現修正後的草稿
7. 提出規格      → 完整代理規格書 (參見 templates/agent-spec.md)
8. 核准關卡     → 使用者建構前核准

範圍訪談 (8 個領域)

對於 Quick 層級: 全部跳過 — 直接從頭開始推論 + 確認

對於 Standard+:

  1. 從現有上下文推論草稿規格 → 將單頁草稿呈現給使用者
  2. 使用者閱讀後標記修正(修改/增加/刪除)
  3. 使用下方檢查清單檢查是否有遺漏 — 僅針對草稿未涵蓋的部分提問
  4. 套用原型最小化清單 — 根據原型進行簡短 / 明顯則跳過 / 深入

嚴禁逐項詢問檢查清單 — 先呈現草稿,僅針對缺口提問

領域 1:身份與目的 (Identity & Purpose)

  • 名稱 — 代理叫什麼?(如果尚未命名,請提議)

  • 原型 — 根據目錄屬於哪個原型?

  • 角色 — 一句清楚的句子:「這個代理[做 X 事]給[使用者 Y],以達成[Z]。」

  • 人格 (Persona) —

    欄位內容範例
    Tone正式 / 隨意 / 技術性 / 好玩 / 權威 / 溫暖「技術性但平易近人」
    範例句代理實際會說的話「讓我檢查一下設定... 找到了。問題在第 42 行。」

    務必推薦一個人格。

    「我建議採用技術性但平易近人的語氣 —
     事實精確,對話輕鬆。」
    
  • 已知上下文 — 在開始工作前必須知道什麼?

  • 最狹義的工作 — 其角色最有用的最小定義是什麼?

領域 2:能力與邊界 (Capabilities & Boundaries)

  • 能力 (Capabilities) — 核心動作,按優先順序排列。 每個能力包括:

    • 描述(1 句話)
    • 觸發條件(如何呼叫此能力?)
    • 預期輸出(成功的樣子是什麼?)
    • 失敗模式(如果它不工作會怎樣?)
  • 邊界 (Boundaries) — 明確列出它絕對不能做的事。 每個邊界都以關鍵規則格式呈現,並附帶情境:

    規則:嚴禁修改專案目錄外的檔案。
    情境:使用者要求「修復我的桌面設定」— 代理有檔案系統存取權。
    後果:有禮貌地拒絕,解釋範圍限制。
    
  • 工具映射 (Tool Mapping) — 對於每個能力,決定需要哪些工具。 請在能力和邊界明確之後再進行此步驟。

    能力:「搜尋文件」
    ↓
    搜尋程式碼庫中現有工具 → 找到 Exa MCP(網路搜尋)
    ↓
    建議:「透過 Exa MCP(已設定)進行知識檢索。
             若 Exa 不可用,則備用透過 Firecrawl 進行網路搜尋。」
    

    規則: 如果程式碼庫中已有特定工具,請提議使用該工具。 僅在沒有現有工具符合需求時,才提議一個類別。 但是: 如果現有工具與需求不匹配(例如需要本地文件搜尋,但只有 Exa 網路搜尋)— 嚴禁硬塞 (force-fit)。將其標記為部分符合或缺口,並提議更符合的類別。

    ✅ 「使用 Exa MCP 進行網路搜尋 — 已設定」
    ✅ 「Exa MCP 可用於網路搜尋,但工作日誌搜尋應使用
        Obsidian + grep 替代 — 對於外部搜尋算是部分符合」
    ✅ 「未找到現有向量資料庫。需要一個語意搜尋工具,
        例如 Chroma 或 Qdrant。」
    ❌ 「需要一個知識檢索工具」(含糊 — Exa 已存在,使用它)
    ❌ 「為所有功能使用 Exa MCP」(硬塞 — Exa 不適合本地搜尋)
    

    工具類別(供參考缺口用):

    Knowledge retrieval    → search, vector DBs, document stores, web scraping
    Code execution         → sandboxes, interpreters, compilers, linters
    Communication          → email, messaging, notifications, webhooks
    System operations      → file I/O, process management, network, registry
    Data processing        → ETL, transformation, validation, storage
    Visual/creative        → image generation, layout engines, animation
    Monitoring             → logs, metrics, tracing, alerting
    AI/LLM                 → model APIs, embeddings, RAG pipelines, vector DBs
    Testing                → test runners, coverage, mocking, E2E browsers
    
  • 技能 (Skills) — 需要哪些技能?

    …

[因篇幅限制,內容已截斷]

相關技能