SamuelChien/mega-skills-collection

Claude Code 外掛程式的代理開發

概覽

代理 (Agent) 是能獨立處理複雜多步驟任務的自主子進程。理解代理結構、觸發條件與系統提示設計，有助於打造強大的自主功能。

關鍵概念：

• 代理是「為了」自主工作，指令則是「為了」使用者啟動的操作
• 採用含有 YAML frontmatter 的 Markdown 檔案格式
• 透過 description 欄位與範例觸發
• 系統提示定義代理行為
• 可自訂模型與顏色

代理檔案結構

完整格式

---
name: agent-identifier
description: 當 [觸發條件] 時使用此代理。範例：

<example>
Context: [情境描述]
user: "[使用者請求]"
assistant: "[助手應如何回應並使用此代理]"
<commentary>
[為何應觸發此代理]
</commentary>
</example>

<example>
[更多範例...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

您是 [代理角色描述]...

**您的核心職責：**
1. [職責 1]
2. [職責 2]

**分析流程：**
[逐步工作流程]

**輸出格式：**
[應回傳的內容]

Frontmatter 欄位

name (必填)

用於命名空間與呼叫的代理識別碼。

格式： 僅限小寫字母、數字與連字號 長度： 3-50 個字元 規則： 必須以英數字元開頭與結尾

良好範例：

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

不良範例：

• helper (過於通用)
• -agent- (以連字號開頭/結尾)
• my_agent (不允許底線)
• ag (太短，少於 3 個字元)

description (必填)

定義 Claude 何時應觸發此代理。這是最關鍵的欄位。

必須包含：

1. 觸發條件 (「當...時使用此代理」)
2. 展示使用方式的多個 <example> 區塊
3. 每個範例中的 Context、user 要求與 assistant 回應
4. 解釋為何觸發代理的 <commentary>

格式：

當 [條件] 時使用此代理。範例：

<example>
Context: [情境描述]
user: "[使用者說的話]"
assistant: "[Claude 應如何回應]"
<commentary>
[為何此代理是合適的]
</commentary>
</example>

[更多範例...]

最佳實務：

• 包含 2-4 個具體範例
• 展示主動與被動觸發
• 涵蓋相同意圖的不同措辭
• 在 commentary 中解釋理由
• 明確說明何時「不」使用此代理

model (必填)

代理應使用的模型。

選項：

• inherit - 使用與父層相同的模型 (建議)
• sonnet - Claude Sonnet (平衡)
• opus - Claude Opus (功能最強，成本最高)
• haiku - Claude Haiku (快速，便宜)

建議： 除非代理需要特定模型功能，否則使用 inherit。

color (必填)

代理在使用者介面中的視覺識別色。

選項： blue, cyan, green, yellow, magenta, red

指南：

• 同一外掛程式的不同代理應選擇不同的顏色
• 對類似類型的代理使用一致的顏色
• 藍色/青色：分析、審查
• 綠色：成功導向任務
• 黃色：謹慎、驗證
• 紅色：關鍵、安全
• 洋紅色：創意、產生

tools (選填)

限制代理使用的特定工具。

格式： 工具名稱陣列

tools: ["Read", "Write", "Grep", "Bash"]

預設值： 若省略，代理有權使用所有工具

最佳實務： 將工具限制在最小必要範圍 (最小權限原則)

常用工具組合：

• 唯讀分析：["Read", "Grep", "Glob"]
• 程式碼產生：["Read", "Write", "Grep"]
• 測試：["Read", "Bash", "Grep"]
• 完全存取：省略此欄位或使用 ["*"]

系統提示設計

Markdown 主體會成為代理的系統提示。請使用第二人稱，直接對代理說話。

結構

標準範本：

您是專精於 [領域] 的 [角色]。

**您的核心職責：**
1. [主要職責]
2. [次要職責]
3. [其他職責...]

**分析流程：**
1. [步驟一]
2. [步驟二]
3. [步驟三]
[...]

**品質標準：**
- [標準 1]
- [標準 2]

**輸出格式：**
請依以下格式提供結果：
- [應包含的內容]
- [如何結構化]

**邊界案例：**
處理以下情況：
- [邊界案例 1]：[如何處理]
- [邊界案例 2]：[如何處理]

最佳實務

✅ 請務必：

• 使用第二人稱書寫 (「您是...」、「您將...」)
• 具體說明職責
• 提供逐步流程
• 定義輸出格式
• 包含品質標準
• 處理邊界案例
• 保持在 10,000 字元以內

❌ 請勿：

• 使用第一人稱書寫 (「我是...」、「我將...」)
• 模糊或通用
• 省略流程步驟
• 未定義輸出格式
• 跳過品質指引
• 忽略錯誤案例

建立代理

方法 1：AI 輔助產生

使用此提示模式 (取自 Claude Code)：

根據此要求建立代理設定：「[您的描述]」

需求：
1. 萃取核心意圖與職責
2. 針對該領域設計專家角色
3. 建立全面的系統提示，包含：
   - 明確的行為邊界
   - 特定方法論
   - 邊界案例處理
   - 輸出格式
4. 建立識別碼 (小寫、連字號、3-50 個字元)
5. 撰寫包含觸發條件的 description
6. 加入 2-3 個顯示何時使用的 <example> 區塊

回傳 JSON，格式為：
{
  "identifier": "agent-name",
  "whenToUse": "當...時使用此代理。範例：<example>...</example>",
  "systemPrompt": "您是..."
}

然後將其轉換為含 frontmatter 的代理檔案格式。

完整範本請參閱 examples/agent-creation-prompt.md。

方法 2：手動建立

1. 選擇代理識別碼 (3-50 個字元，小寫，連字號)
2. 撰寫包含範例的 description
3. 選擇模型 (通常為 inherit)
4. 選擇視覺識別色
5. 定義工具 (若需限制存取)
6. 依照上述結構撰寫系統提示
7. 儲存為 agents/agent-name.md

驗證規則

識別碼驗證

✅ 有效：code-reviewer, test-gen, api-analyzer-v2
❌ 無效：ag (太短), -start (以連字號開頭), my_agent (底線)

規則：

• 3-50 個字元
• 僅限小寫字母、數字、連字號
• 必須以英數字元開頭與結尾
• 無底線、空格或特殊字元

Description 驗證

長度： 10-5,000 字元 必須包含： 觸發條件與範例 最佳長度： 200-1,000 字元，2-4 個範例

系統提示驗證

長度： 20-10,000 字元 最佳長度： 500-3,000 字元 結構： 明確的職責、流程、輸出格式

代理組織

外掛程式代理目錄

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

agents/ 中的所有 .md 檔案都會被自動發現。

命名空間

代理會自動被命名空間化：

• 單一外掛程式：agent-name
• 包含子目錄：plugin:subdir:agent-name

測試代理

測試觸發

建立測試情境以驗證代理正確觸發：

1. 撰寫包含特定觸發範例的代理
2. 在測試中使用與範例相似的措辭
3. 檢查 Claude 是否載入代理
4. 驗證代理提供預期功能

測試系統提示

確保系統提示完整：

1. 給予代理典型任務
2. 檢查是否遵循流程步驟
3. 驗證輸出格式是否正確
4. 測試提示中提及的邊界案例
5. 確認滿足品質標準

快速參考

最小代理

---
name: simple-agent
description: 當...時使用此代理。範例：<example>...</example>
model: inherit
color: blue
---

您是執行 [X 任務] 的代理。

流程：
1. [步驟 1]
2. [步驟 2]

輸出：[應提供的內容]

Frontmatter 欄位摘要

欄位	必填	格式	範例
name	是	lowercase-hyphens	code-reviewer
description	是	文字 + 範例	當...時使用 ...
model	是	inherit/sonnet/opus/haiku	inherit
color	是	顏色名稱	blue
tools	否	工具名稱陣列	["Read", "Grep"]

最佳實務

請務必：

• ✅ 在 description 中包含 2-4 個具體範例
• ✅ 撰寫特定的觸發條件
• ✅ 除非有特定需求，否則對 model 使用 inherit
• ✅ 選擇合適的工具 (最小權限)
• ✅ 撰寫清晰、結構化的系統提示
• ✅ 徹底測試代理觸發

請勿：

• ❌ 使用不包含範例的通用描述
• ❌ 省略觸發條件
• ❌ 給予所有代理相同顏色
• ❌ 授權不必要的工具存取
• ❌ 撰寫模糊的系統提示
• ❌ 跳過測試

其他資源

參考檔案

如需詳細指引，請諮詢：

• references/system-prompt-design.md - 完整的系統提示模式
• references/triggering-examples.md - 範例格式與最佳實務
• references/agent-creation-system-prompt.md - Claude Code 的確切提示

範例檔案

examples/ 中的實作範例：

• agent-creation-prompt.md - AI 輔助代理產生範本
• complete-agent-examples.md - 不同使用案例的完整代理範例

公用腳本

scripts/ 中的開發工具：

• validate-agent.sh - 驗證代理檔案結構
• test-agent-trigger.sh - 測試代理是否正確觸發

實作工作流程

若要為外掛程式建立代理：

1. 定義代理目的與觸發條件
2. 選擇建立方法 (AI 輔助或手動)
3. 建立 agents/agent-name.md 檔案
4. 撰寫包含所有必填欄位的 frontmatter
5. 遵循最佳實務撰寫系統提示
6. 在 description 中包含 2-4 個觸發範例
7. 使用 scripts/validate-agent.sh 進行驗證
8. 使用真實情境測試觸發
9. 在外掛程式 README 中記錄代理

專注於清晰的觸發條件與全面的系統提示，以實現自主操作。