> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/advanced-genai-tech/skill.md).

# Skill 技能模組

Skill 技能模組技術說明：把任務指令、工具與資源檔封裝成 Agent 按需展開的能力單元，SKILL.md 規格、觸發條件、技能包結構與 API 端點。

## 什麼是 Skill？

Skill（技能）把一套任務指令、附加工具與資源檔案封裝成 Agent 可以按需展開的能力單元；概念、適用情境與後台操作見使用者手冊的[技能](https://docs.maiagent.ai/build/skills)，本頁說明運作原理、`SKILL.md` 規格與 API。

<figure><img src="https://527168072-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F38pkhhqHl1oA6yyE9R2n%2Fuploads%2Fgit-blob-d8cf8aa85fc73203db4a2e33e8b6a38fa0d69035%2Fskill-composition.png?alt=media" alt=""><figcaption><p>技能（Skill）= 指令（Instructions）+ 工具（Tools）+ 資源（Resources）</p></figcaption></figure>

***

## Skill 的運作原理

### 運作流程

```
使用者提問
    │
    ▼
Agent 接收訊息（已帶有可用技能清單：名稱＋使用時機）
    │
    ▼
LLM 分析意圖，比對技能的使用時機
    │
    ├─ 匹配到技能 → 呼叫 skill_expand_tool
    │                    │
    │                    ▼
    │              取得技能的完整指令內容
    │              ＋附加工具名稱（已隨技能一起掛載）
    │              ＋資源檔案位置（有開 Code Interpreter 時）
    │                    │
    │                    ▼
    │              LLM 依指令逐步執行、呼叫附加工具
    │                    │
    │                    ▼
    │              LLM 依指令格式生成回覆
    │
    └─ 未匹配 → 一般對話回覆
```

### 1. 技能清單 <a href="#skill-list" id="skill-list"></a>

Agent 綁定技能後，模型一開始只會看到每個技能的名稱與使用時機：取 `SKILL.md` 的 `when_to_use`，沒填時用 `description`。完整指令不會預先放進上下文。

### 2. 技能展開（Skill Expansion） <a href="#skill-expansion" id="skill-expansion"></a>

當模型判斷問題應由某個技能處理時，會呼叫 `skill_expand_tool`：

* **輸入**：技能名稱（`skill_name`，不分大小寫）
* **輸出**：JSON，包含技能的完整指令（`instructions`）、使用時機、附加工具名稱（`attached_tools`），以及資源檔案清單與所在目錄（`resource_files`、`resource_directory`）

```json
{
  "name": "skill_expand_tool",
  "arguments": {
    "skill_name": "休假天數計算"
  }
}
```

### 3. 附加工具與資源檔案 <a href="#attached-tools-and-resources" id="attached-tools-and-resources"></a>

* **附加工具**：技能綁定的 API 工具與 MCP 工具，會在對話開始時就和技能一起掛載，模型展開技能後可以直接呼叫，不需要另外載入。
* **資源檔案**：Agent 開啟 Code Interpreter 時，展開技能會把資源檔案載入沙盒的 `/workspace/skills/<技能名稱>/` 目錄，模型可以用程式讀取。沒有開啟 Code Interpreter 時，模型只拿得到指令內容。

***

## SKILL.md 規格

Skill 的核心定義檔案為 `SKILL.md`，使用 YAML Frontmatter + Markdown 內容格式：

```markdown
---
name: 技能名稱
description: 技能描述（決定 AI 何時觸發此技能）
---

# 技能標題

## 觸發條件
使用者詢問 XXX 相關問題時觸發。

## 執行步驟

### Step 1：確認資訊
引導使用者提供必要資訊...

### Step 2：查詢資料
使用 retrieve_text_nodes 搜尋知識庫...

### Step 3：產出回覆
依照以下格式回覆：
- ① 適用法規
- ② 計算結果
- ③ 參考範例
```

### Frontmatter 欄位

| 欄位            | 必填 | 說明                                       |
| ------------- | -- | ---------------------------------------- |
| `name`        | 是  | 技能名稱，組織內不可重複                             |
| `description` | 是  | 技能描述；沒有填 `when_to_use` 時，LLM 用它判斷是否觸發此技能 |
| `when_to_use` | 否  | 使用時機，LLM 優先以它判斷是否觸發此技能                   |

### 指令內容撰寫建議

1. **觸發條件明確**：在描述和指令中清楚定義「何時觸發」與「何時不觸發」
2. **步驟結構化**：使用編號步驟（Step 1, Step 2...）讓 LLM 能循序執行
3. **工具呼叫指引**：在步驟中明確指出應使用哪個工具與查詢策略
4. **回覆格式定義**：用模板或表格定義最終回覆的格式，確保輸出一致性
5. **防錯清單**：在指令末尾加入檢查清單，讓 LLM 自我驗證結果

***

## 技能包（Skill Package）

### 檔案結構

上傳的 `.skill` 或 `.zip` 檔案應包含以下結構：

```
my-skill.skill (ZIP 格式)
├── SKILL.md          # 必要：技能定義檔
├── reference.pdf     # 選填：參考資料
├── template.xlsx     # 選填：模板檔案
└── examples/         # 選填：範例資料
    └── case1.json
```

### 安全性驗證

系統在解析技能包時會進行以下安全檢查：

* **壓縮比檢查**：最大 100:1，防止 ZIP 炸彈攻擊
* **路徑遍歷防護**：阻擋 `../` 等路徑注入
* **檔案大小限制**：依組織設定的上傳限制（預設 100 MB）
* **SKILL.md 驗證**：必須存在且包含有效的 `name` 和 `description`

***

## API 端點

### Skill CRUD

| 方法       | 端點                     | 說明                 |
| -------- | ---------------------- | ------------------ |
| `GET`    | `/api/v1/skills/`      | 列出組織內所有技能（支援分頁、搜尋） |
| `POST`   | `/api/v1/skills/`      | 手動建立技能             |
| `GET`    | `/api/v1/skills/{id}/` | 取得技能詳情             |
| `PATCH`  | `/api/v1/skills/{id}/` | 更新技能               |
| `DELETE` | `/api/v1/skills/{id}/` | 刪除技能（含 S3 清理）      |

### 技能包操作

| 方法     | 端點                                       | 說明                        |
| ------ | ---------------------------------------- | ------------------------- |
| `POST` | `/api/v1/skills/upload/`                 | 上傳 `.skill` / `.zip` 建立技能 |
| `POST` | `/api/v1/skills/{id}/reupload/`          | 重新上傳替換技能包                 |
| `GET`  | `/api/v1/skills/{id}/export/`            | 匯出技能為 `.skill` 檔案         |
| `GET`  | `/api/v1/skills/{id}/package-structure/` | 查看技能包檔案結構                 |

### 資源管理（巢狀路由）

| 方法       | 端點                                              | 說明       |
| -------- | ----------------------------------------------- | -------- |
| `GET`    | `/api/v1/skills/{id}/resources/`                | 列出技能資源檔案 |
| `POST`   | `/api/v1/skills/{id}/resources/`                | 上傳資源檔案   |
| `DELETE` | `/api/v1/skills/{id}/resources/{rid}/`          | 刪除資源檔案   |
| `GET`    | `/api/v1/skills/{id}/resources/{rid}/download/` | 下載資源檔案   |

### 手動建立的請求欄位 <a href="#create-skill-fields" id="create-skill-fields"></a>

`POST /api/v1/skills/` 以 JSON 建立技能（`Authorization: Api-Key <金鑰>`、`Content-Type: application/json`）。欄位名稱 camelCase 與 snake\_case 都接受，回應一律 camelCase：

| 欄位                | 必填  | 說明                                                                                                |
| ----------------- | --- | ------------------------------------------------------------------------------------------------- |
| `name`            | 是   | 技能名稱，組織內不可重複；只能用可當資料夾名稱的字元                                                                        |
| `description`     | 是   | 技能描述；沒有 `whenToUse` 時模型以它判斷是否觸發                                                                   |
| `whenToUse`       | 否   | 使用時機，模型優先以它判斷是否觸發                                                                                 |
| `instructions`    | 是   | `SKILL.md` 的內容（Markdown）                                                                          |
| `attachedToolIds` | 否   | 要附加的工具 ID 陣列，只接受啟用中的工具；回應中不會回傳這個欄位，改以 `attachedTools` 列出工具摘要                                      |
| `groups`          | 視身分 | `[{"id": "<角色 ID>"}]`；組織 owner 可不帶，其他成員至少要指定一個自己所屬的角色，否則回 `400`                                   |
| `files`           | 否   | 隨技能一起建立的資源檔，每項 `{"path": "scripts/run.py", "content": "…", "contentEncoding": "text" 或 "base64"}` |

成功回 `201`，內容是技能物件（含 `id`、`createdAt`、`resources`）；名稱重複、工具 ID 無效或角色不合規回 `400`，內容是欄位錯誤或 `{"detail": "…"}`。更新用 `PATCH /api/v1/skills/{id}/`，欄位同上（`files` 除外），改到 `name`、`description`、`whenToUse`、`instructions` 任一項會重新產生 `SKILL.md`。

### 建立技能範例

**手動建立：**

```json
POST /api/v1/skills/
{
  "name": "退貨處理流程",
  "description": "處理客戶的退貨與換貨申請：查詢訂單、確認退貨資格、建立退貨單。",
  "whenToUse": "客戶提到退貨、換貨、退款時觸發",
  "instructions": "# 退貨處理\n\n## Step 1：查詢訂單\n...",
  "attachedToolIds": [
    "uuid-of-order-query-tool",
    "uuid-of-return-api-tool"
  ]
}
```

**上傳技能包：**

```bash
curl -X POST /api/v1/skills/upload/ \
  -F "file=@my-skill.skill" \
  -F "attached_tool_ids=[\"uuid-1\",\"uuid-2\"]"
```

***

## 技能與 Agent 的綁定 <a href="#ji-neng-yu-ai-zhu-li-de-bang-ding" id="ji-neng-yu-ai-zhu-li-de-bang-ding"></a>

技能透過 `ChatbotSkill` 中介模型與 Agent 建立多對多關聯：

* 一個 Agent 可綁定多個技能
* 一個技能可被多個 Agent 使用
* 綁定/解綁操作會記錄在 `ChatbotSkillEvent` 歷史追蹤表中

```
Agent A ──┬── 技能：退貨處理
          ├── 技能：產品諮詢
          └── 技能：郵件發送

Agent B ──┬── 技能：產品諮詢  ← 共用
          └── 技能：會議查詢
```

***

## 設計特性與限制 <a href="#design-and-limitations" id="design-and-limitations"></a>

### 指令與工具分開管理 <a href="#instructions-and-tools" id="instructions-and-tools"></a>

技能保存的是指令內容、使用時機與資源檔案；附加工具是對組織既有工具的參照。修改技能指令不會改到工具設定；修改工具本身（網址、標頭等）則會影響所有附加了這個工具的技能與綁定它的 Agent。

### 按需展開 <a href="#on-demand-expansion" id="on-demand-expansion"></a>

技能的完整指令要等模型呼叫 `skill_expand_tool` 才進入上下文，未展開的技能只佔名稱與使用時機，見[技能清單](#skill-list)。因此技能是否被使用，取決於模型能否從使用時機判斷出來；使用時機寫得模糊時，技能可能不會被展開。建議在使用時機寫出常見說法與「不適用」的情況。

### 匯出與跨組織匯入 <a href="#export-and-import" id="export-and-import"></a>

* 匯出的 `.skill` 檔包含 `SKILL.md` 與所有資源檔案。手動建立的技能匯出時，系統產生的 `SKILL.md` 會一併帶上使用時機與附加工具名稱。
* 在其他組織上傳時，系統依工具名稱重新綁定該組織的工具；找不到對應工具的項目（包含沒有工具名稱的 MCP 工具）會列在上傳結果中，需要手動綁定。
* 工具本身與其憑證不會隨技能包匯出。

### 重新上傳 <a href="#reupload" id="reupload"></a>

上傳方式建立的技能可以重新上傳（Reupload），新技能包會取代技能的名稱、描述、指令內容與所有資源檔案，舊的資源檔案會被刪除。平台不保留舊版技能包，需要回復時請自行保存先前的 `.skill` 檔。手動建立的技能不能重新上傳。

### 權限控管 <a href="#permissions" id="permissions"></a>

技能頁面的存取受「<mark style="color:blue;">技能權限</mark>」（`chatbot_skill_access`）控制。組織自建的技能可以分配給角色，每一筆「角色 × 技能」可個別設定讀取、編輯、刪除；角色另有「<mark style="color:blue;">允許新增技能</mark>」開關。設定方式見使用手冊的[依角色控管技能可見性與權限](https://docs.maiagent.ai/build/skills/skills-management#skill-role-visibility)。

***

## 操作請看使用手冊 <a href="#user-guide-links" id="user-guide-links"></a>

* [技能](https://docs.maiagent.ai/build/skills)：概念與適用情境
* [技能管理](https://docs.maiagent.ai/build/skills/skills-management)：建立、上傳、附加工具、匯出與綁定 Agent


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/advanced-genai-tech/skill.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
