create-custom-agent

建立自訂代理

此技能協助您建立 VS Code 自訂代理檔案，為開發任務定義專業的 AI 角色。自訂代理可設定可用的工具、提供專業指令，並可透過交接串聯多步驟工作流程。

使用時機

• 從零開始建立新的自訂代理
• 建立具備正確 frontmatter 的 .agent.md 檔案
• 為多步驟工作流程設定代理間交接
• 為專業角色（如 planner、reviewer 等）設定工具限制
• 建立工作區共用或使用者設定檔代理

不適合使用時機

• 建立指令檔案（請改用 .instructions.md）
• 建立可重複使用的提示（請改用 .prompt.md）
• 修改現有代理（請直接編輯檔案）

輸入

輸入	必填	說明
代理名稱	是	代理的描述性名稱（例如 planner、code-reviewer）
說明	是	在聊天中顯示為佔位文字的簡短說明
用途/角色	是	代理扮演的角色及其行為方式
工具	建議	代理可使用的工具或工具集清單
交接	選填	完成工作後要轉交的下一個代理

工作流程

步驟 1：建立代理檔案

在 agents/ 目錄中建立副檔名為 .agent.md 的檔案：

agents/<agent-name>.agent.md

步驟 2：加入 YAML frontmatter

加入包含必填與選填欄位的標頭：

---
name: <agent-name>
description: <brief description for chat placeholder>
tools:
  - <tool-name>
  - <tool-set-name>
---

可用的 frontmatter 欄位：

欄位	必填	說明
name	否	顯示名稱（預設為檔案名稱）
description	是	在聊天輸入中顯示的佔位文字
argument-hint	否	引導使用者互動的提示文字
tools	否	可用工具/工具集清單
agents	否	允許的子代理清單（* 表示全部，[] 表示無）
model	否	AI 模型名稱或依優先順序排列的模型陣列
handoffs	否	下一步代理交接清單
user-invokable	否	在代理下拉選單中顯示（預設：true）
disable-model-invocation	否	防止子代理被呼叫（預設：false）
target	否	目標環境：vscode 或 github-copilot
mcp-servers	否	適用於 GitHub Copilot 目標的 MCP 伺服器設定

步驟 3：設定工具

指定代理可使用的工具：

tools:
  - search              # 內建工具
  - fetch               # 內建工具
  - codebase            # 工具集
  - myServer/*          # 來自 MCP 伺服器的所有工具

常見工具模式：

• 唯讀代理：['search', 'fetch', 'codebase']
• 完整編輯代理：['*'] 或特定編輯工具
• 專業代理：挑選特定工具

步驟 4：加入交接（選填）

設定轉交其他代理的設定：

handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)

交接欄位：

• label：顯示給使用者的按鈕文字
• agent：目標代理識別碼
• prompt：預先填入的目標代理提示
• send：自動送出提示（預設：false）
• model：選填，交接時使用的模型覆寫

步驟 5：撰寫代理指令（本文）

以 Markdown 加入代理的行為指令：

You are a security-focused code reviewer. Your job is to:

1. Analyze code for security vulnerabilities
2. Check for common security anti-patterns
3. Suggest secure alternatives

## Guidelines

- Focus on OWASP Top 10 vulnerabilities
- Flag hardcoded secrets immediately
- Review authentication and authorization logic

## Reference other files

See [security guidelines](../security.md) for standards.

指令撰寫技巧：

• 使用 Markdown 連結參照其他檔案
• 使用 #tool:<tool-name> 語法參照工具
• 明確描述代理的行為與限制

步驟 6：驗證代理

確認代理能正確載入：

1. 開啟命令面板（Ctrl+Shift+P）
2. 執行「Chat: New Custom Agent」或檢查代理下拉選單
3. 使用「Diagnostics」檢視（在聊天檢視中按右鍵）檢查錯誤

範本

---
name: <agent-name>
description: <brief description for chat placeholder>
argument-hint: <optional hint for user input>
tools:
  - <tool-1>
  - <tool-2>
handoffs:
  - label: <button-text>
    agent: <target-agent>
    prompt: <pre-filled-prompt>
    send: false
---

# <Agent Title>

<One paragraph describing the agent's persona and purpose.>

## Role

<Describe the agent's specialized role and expertise.>

## Guidelines

- <Guideline 1>
- <Guideline 2>
- <Guideline 3>

## Workflow

1. <Step 1>
2. <Step 2>
3. <Step 3>

## Constraints

- <Constraint 1>
- <Constraint 2>

代理範例

規劃代理

---
name: planner
description: Generate an implementation plan
tools:
  - search
  - fetch
  - codebase
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan above.
---

# Planning Agent

You are a solution architect. Generate detailed implementation plans.

## Guidelines

- Analyze requirements thoroughly before planning
- Break work into discrete, testable steps
- Identify dependencies and risks
- Do NOT make code changes

程式碼審查代理

---
name: code-reviewer
description: Review code for quality and security issues
tools:
  - search
  - codebase
---

# Code Review Agent

You are a senior engineer performing code review.

## Focus Areas

- Security vulnerabilities
- Performance concerns
- Code maintainability
- Test coverage gaps

## Output Format

Provide findings as:
1. **Critical**: Must fix before merge
2. **Warning**: Should address
3. **Suggestion**: Nice to have

驗證檢查清單

• [ ] 檔案副檔名為 .agent.md
• [ ] 檔案位於 agents/ 目錄中
• [ ] YAML frontmatter 有效（縮排正確、無語法錯誤）
• [ ] 說明非空且具描述性
• [ ] 工具清單僅包含可用的工具
• [ ] 交接代理名稱與現有代理相符
• [ ] 指令清晰且可執行
• [ ] 代理出現在代理下拉選單中

常見問題

問題	解決方法
代理未出現在下拉選單中	檢查檔案是否位於 agents/ 目錄且副檔名為 .agent.md
YAML 語法錯誤	驗證 frontmatter 的縮排與引號
工具無法運作	確認工具名稱存在；無法使用的工具會被忽略
交接未顯示	目標代理必須存在；檢查代理識別碼
指令過於模糊	明確描述角色、限制與工作流程
代理意外被當作子代理呼叫	設定 disable-model-invocation: true
希望代理僅作為子代理	設定 user-invokable: false

參考資料

• VS Code 自訂代理文件
• 聊天中的工具
• 自訂指令
• 提示檔案