第 6 章：代理技能開發

6.1 什麼是 Skills？

Skills 是 OpenCode 中的可重用指令單元。每個 Skill 以一個 SKILL.md 檔案為核心，內含結構化的步驟指引，讓代理在特定任務中表現得更專業、更一致。

你可以把 Skill 想像成一個「專業知識包」：當代理遇到符合觸發條件的任務時，會自動載入對應的 Skill，按照其中的指引執行任務。這讓你不必每次重複描述同樣的工作流程。

6.2 Skill 的發現機制

OpenCode 會從以下位置依序搜尋可用的 Skills：

當名稱衝突時，優先順序較高的路徑會覆蓋較低的路徑。這表示你可以在專案層級覆蓋全域技能，以滿足特定專案的需求。

6.3 SKILL.md 格式

一個完整的 Skill 檔案包含兩個部分：Frontmatter（後設資料）與 Markdown 內容（步驟指引）。

Frontmatter 欄位

完整範例

---
name: api-design-review
description: 審查 REST API 設計，確保符合最佳實作與 OpenAPI 規範
triggers:
  - api review
  - rest api
  - openapi
  - endpoint design
---

# API 設計審查技能

當你需要審查 API 設計時，請依以下步驟進行：

## 1. 收集資訊
- 取得 API 規格文件（OpenAPI / Swagger）
- 了解使用案例與消費端需求
- 確認現有的 API 設計準則

## 2. 審查項目

### URL 設計
- [ ] 使用名詞而非動詞（`/users` 而非 `/getUsers`）
- [ ] 版本控制（`/v1/users`）
- [ ] 一致的複數形式
- [ ] 適當的巢狀結構（`/users/{id}/orders`）

### HTTP 方法
- [ ] GET：讀取資源（唯讀、幂等）
- [ ] POST：建立資源（非幂等）
- [ ] PUT：完整更新（幂等）
- [ ] PATCH：部分更新
- [ ] DELETE：刪除資源（幂等）

### 回應設計
- [ ] 一致的錯誤格式（`{ error, message, code }`）
- [ ] 適當的 HTTP 狀態碼
- [ ] 分頁支援（`page`, `per_page`, `total`）
- [ ] 欄位選擇（`?fields=id,name`）

## 3. 輸出格式

```markdown
## API 審查結果

### 違反規範 (N 項)
| 端點 | 問題 | 嚴重性 | 建議 |
|------|------|--------|------|

### 整體評分
- RESTful 程度: X/10
- 一致性: X/10
- 安全性: X/10
- 文件完整性: X/10
```

6.4 建立你的第一個 Skill

讓我們透過一個實際案例，逐步建立一個「React 元件生成器」技能：

步驟 1：建立目錄結構

# 在專案中建立技能目錄
mkdir -p .opencode/skills/react-component-gen

步驟 2：建立 SKILL.md

在目錄中建立 SKILL.md 檔案：

---
name: react-component-gen
description: 根據規格生成 React 元件，包含 TypeScript 型別、測試與 Storybook 故事
triggers:
  - react component
  - 產生元件
  - create component
---

# React 元件生成器

根據需求自動生成結構完整的 React 元件。

## 輸入需求

請確認以下資訊：
- 元件名稱（PascalCase）
- Props 型別定義
- 使用場景與行為描述
- 是否包含測試（預設：是）
- 是否包含 Storybook 故事（預設：是）

## 輸出結構

```
src/components/{ComponentName}/
├── {ComponentName}.tsx        # 元件實作
├── {ComponentName}.types.ts   # Props 型別
├── {ComponentName}.test.tsx   # 單元測試
├── {ComponentName}.stories.tsx # Storybook
└── index.ts                   # 匯出檔案
```

## 實作規範

1. 使用函式元件與 React Hooks
2. 所有 Props 需定義 TypeScript 型別
3. 使用 CSS Modules 或 Tailwind CSS
4. 支援 ref 轉發（forwardRef）
5. 加入 displayName
6. 測試覆蓋：render、props、event handler、edge cases

步驟 3：測試技能

在對話中輸入以下內容，OpenCode 會自動偵測觸發詞並載入技能：

請幫我產生一個 React 元件：一個可搜尋的下拉選單（SearchableSelect），
支援非同步載入選項、鍵盤導航與自訂選項模板。

步驟 4：手動載入技能

你也可以直接要求代理載入特定技能：

使用 react-component-gen 技能，建立一個 Modal 元件。

6.5 內建 Skills

OpenCode 隨附多個內建技能，涵蓋常見的開發任務：

內建技能位於 OpenCode 安裝目錄中，你無需手動建立即可直接使用。隨著 OpenCode 版本更新，內建技能也會持續增加與改進。

6.6 Skill 權限管理

每個 Skill 可以設定自己的工具權限，確保技能在安全的範圍內運作：

---
name: readonly-doc-generator
description: 只能讀取檔案來產生文件，不會修改任何程式碼
permissions:
  allow:
    - read
    - grep
    - glob
  deny:
    - write
    - edit
    - bash
    - webfetch
---

# 唯讀文件產生器

這個技能只能讀取檔案，無法修改任何內容。
適合用於自動化文件產生與程式碼分析任務。

6.7 Skill 的進階技巧

鏈式技能呼叫

你可以在一個 Skill 的內容中引用其他 Skill，形成處理管線：

# 完整發佈流程

此技能會依序啟動以下技能：
1. 使用「test-runner」技能執行測試
2. 使用「code-review」技能審查程式碼
3. 使用「documentation」技能更新文件
4. 使用「release」技能執行發佈

每個步驟完成後確認結果，再進入下一步。

條件式技能

根據專案類型使用不同的技能設定：

---
name: project-scaffold
description: 根據技術棧建立初始化專案結構
triggers:
  - scaffold
  - 初始化專案
---

# 專案初始化

偵測到以下技術棧時使用對應範本：

- **React + TypeScript**: src/components/, src/pages/, src/hooks/
- **Python FastAPI**: app/, tests/, alembic/
- **Node.js Library**: src/, test/, examples/

小試身手

常見問題