> 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/build/skills/skills-management.md).

# 技能管理

了解如何建立、編輯與管理技能，包含手動建立、上傳技能包、附加工具與匯出功能

{% hint style="info" %}
如果您還不了解技能是什麼，請先閱讀：[技能](/build/skills.md)
{% endhint %}

## 建立技能 <a href="#create-skill" id="create-skill"></a>

在左側選單中點選 <mark style="color:blue;">技能</mark>，進入技能管理頁面，點擊右上角 <mark style="color:blue;">新增技能</mark> 按鈕。

系統提供兩種建立方式：

### 方式一：手動建立 <a href="#method-manual-create" id="method-manual-create"></a>

適合從零開始撰寫技能指令的情境。

1. 在新增技能彈窗中，點擊下方的 <mark style="color:blue;">手動建立新技能</mark>，切換至手動模式
2. 填寫 <mark style="color:blue;">基本設定</mark> 頁籤：
   * **技能名稱**（必填）：為技能取一個易於辨識的名稱
   * **描述**（必填）：簡要說明技能的用途
3. 切換至 <mark style="color:blue;">指令內容</mark> 頁籤，撰寫 Markdown 格式的指令內容。您也可以點擊 <mark style="color:blue;">套用模板</mark> 按鈕，使用系統提供的預設模板作為起點
4. （選填）切換至 <mark style="color:blue;">附加工具</mark> 頁籤，為技能選擇所需的工具
5. 切換至 <mark style="color:blue;">權限設定</mark> 頁籤，在 <mark style="color:blue;">快速選擇權限範圍</mark> 確認哪些角色的成員可以使用這個技能：<mark style="color:blue;">全部角色</mark>、<mark style="color:blue;">排除預設角色</mark>（預設選取）或 <mark style="color:blue;">自訂選擇角色</mark>。下方的「建立後將分配給」會列出實際分配的角色
6. 點擊 <mark style="color:blue;">儲存</mark> 完成建立

如果還沒打開過 <mark style="color:blue;">權限設定</mark> 頁籤就按 <mark style="color:blue;">儲存</mark>，這次不會建立技能：畫面會自動切到 <mark style="color:blue;">權限設定</mark>，並提示「請先查看權限設定，確認分配的角色後再提交」。確認角色後再按一次 <mark style="color:blue;">儲存</mark>，技能就會依頁籤上顯示的角色建立。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-bd1ed983993c823d22400b5a9a9da575af506530%2Fskills-create-permission-reminder.png?alt=media" alt="新增技能視窗切換到權限設定頁籤，上方提示請先查看權限設定，確認分配的角色後再提交；快速選擇權限範圍有全部角色、排除預設角色（已選取）與自訂選擇角色，下方列出建立後將分配給的角色"><figcaption><p>沒看過權限設定就按儲存時，畫面會切到「權限設定」並提示確認角色</p></figcaption></figure>

{% hint style="info" %}
這道確認只出現在「手動建立」的新技能；以 <mark style="color:blue;">上傳技能包</mark> 建立或編輯既有技能時不會出現。建立後若要調整可使用的角色，請參閱 [依角色控管技能可見性與權限](#skill-role-visibility)。
{% endhint %}

### 方式二：上傳技能包 <a href="#method-upload-skill-package" id="method-upload-skill-package"></a>

適合匯入已封裝好的 `.skill` 或 `.zip` 檔案。

1. 在新增技能彈窗中（預設為上傳模式），將 `.skill` 或 `.zip` 檔案拖曳至上傳區域，或點擊區域選擇檔案
2. 上傳完成後，系統會自動解析檔案中的 `SKILL.md`，提取技能名稱、描述與指令內容
3. 建立成功後會自動跳轉至編輯頁面，您可以進一步調整設定

{% hint style="info" %}
技能包內必須包含 `SKILL.md` 檔案，格式如下：

```markdown
---
name: 技能名稱
description: 技能描述
---

這裡是 AI 助理的執行指令...
```

{% endhint %}

***

## 編輯與設定技能 <a href="#edit-and-configure-skill" id="edit-and-configure-skill"></a>

在技能列表中，點擊該技能的 <mark style="color:blue;">編輯</mark> 圖示，進入技能設定頁面。

### 基本設定 <a href="#basic-settings" id="basic-settings"></a>

編輯技能的名稱與描述。

### 指令內容 <a href="#instruction-content" id="instruction-content"></a>

編輯 Markdown 格式的技能指令。這些指令會在 Agent 展開技能時作為執行依據。

點擊 <mark style="color:blue;">套用模板</mark> 可載入預設的指令模板。

{% hint style="warning" %}
套用模板會覆蓋目前的指令內容，請確認後再執行。
{% endhint %}

### 檔案 <a href="#skill-package" id="skill-package"></a>

<mark style="color:blue;">檔案</mark> 頁籤管理技能的資源檔案，手動建立與上傳建立的技能都有這個頁籤。左側是檔案樹，點選檔案即可在右側預覽內容。這個頁籤的上傳、新增資料夾、刪除與重新上傳會立即生效，不需要另外儲存。

* <mark style="color:blue;">上傳檔案</mark>：上傳參考文件、範本或程式腳本作為技能資源（上限 100 MB）
* <mark style="color:blue;">新增資料夾</mark>：在目前的目錄下建立資料夾，整理資源檔案
* <mark style="color:blue;">下載技能包</mark>：把指令內容與資源檔案打包成 `.skill` 檔下載，見[匯出技能](#export-skill)
* <mark style="color:blue;">重新上傳技能包</mark>：上傳新版本的 `.skill`／`.zip`，取代技能的名稱、描述、指令內容與所有資源檔案；僅適用於上傳方式建立的技能
* 預覽檔案時可個別 <mark style="color:blue;">下載</mark> 或刪除

{% hint style="info" %}
資源檔案要在 Agent 開啟 [Code Interpreter](/build/agent/code-interpreter.md) 時才會被使用：Agent 展開技能後，系統會把檔案放進程式執行環境供 Agent 讀取。沒有開啟 Code Interpreter 的 Agent，只會使用技能的指令內容。
{% endhint %}

### 附加工具 <a href="#additional-tools" id="additional-tools"></a>

為技能綁定所需的工具，讓 Agent 在執行技能時可以調用。

1. 點擊 <mark style="color:blue;">選擇工具</mark> 按鈕，開啟工具選擇彈窗
2. 勾選要附加的工具（支援多選），點擊確認
3. 已選擇的工具會顯示在列表中，包含工具名稱、類型（API / MCP）與描述
4. 如需移除工具，點擊該工具卡片上的刪除圖示

設定完成後，點擊頁面右下角的 <mark style="color:blue;">儲存變更</mark> 按鈕。

***

## 匯出技能 <a href="#export-skill" id="export-skill"></a>

在技能編輯頁面的 <mark style="color:blue;">檔案</mark> 頁籤中，點擊 <mark style="color:blue;">下載技能包</mark> 按鈕即可將技能匯出為 `.skill` 檔案。

{% hint style="info" %}
手動建立的技能也可以匯出，系統會自動將指令內容與資源打包為 `.skill` 檔案。匯出的技能包可分享給其他組織匯入使用。
{% endhint %}

***

## 將技能綁定至 Agent <a href="#bind-skill-to-ai-agent" id="bind-skill-to-ai-agent"></a>

建立好的技能需要綁定至 Agent 才能生效：

1. 前往 <mark style="color:blue;">AI 助理</mark> 頁面，選擇目標 Agent 並進入設置
2. 在模型設置區域找到 <mark style="color:blue;">技能</mark> 設定
3. 選擇要綁定的技能，點擊確認
4. 儲存 Agent 設定

綁定後，Agent 在對話中會根據使用者的問題自動判斷是否需要展開技能，並依照技能指令執行對應任務。

***

## 依角色控管技能可見性與權限 <a href="#skill-role-visibility" id="skill-role-visibility"></a>

若您希望特定角色的成員只看到與工作相關的技能，可以透過角色權限管理，將技能逐一分配給角色。

例如，公司的系統管理員希望業務同仁能讀取「客戶摘要」技能，但不能修改或刪除它。她可以編輯業務角色、分配這項技能並只保留讀取權限。設定完成後，業務同仁可在技能列表看到「客戶摘要」，也不會取得修改或刪除權限。

### 運作規則 <a href="#skill-role-visibility-rules" id="skill-role-visibility-rules"></a>

* **未分配即不可見**：組織自建的技能必須分配給角色，該角色的成員才能在技能列表中看到它；未分配的技能對該角色完全隱藏
* **權限粒度**：每一筆「角色 × 技能」的分配，可個別設定 <mark style="color:blue;">讀取</mark>、<mark style="color:blue;">編輯</mark>、<mark style="color:blue;">刪除</mark> 權限，實現「可讀取但不可修改」等唯讀情境
* **新增權限**：每個角色可獨立設定「允許新增技能」開關，控制該角色成員能否新增技能
* **擁有者不受限**：組織擁有者自動擁有所有技能的完整存取權限，無需分配
* **全域技能例外**：平台內建的全域技能對所有成員可見，無法透過角色分配限制

### 設定步驟 <a href="#skill-role-visibility-steps" id="skill-role-visibility-steps"></a>

{% stepper %}
{% step %}

### 開啟角色設定 <a href="#open-role-settings" id="open-role-settings"></a>

點選左側選單「<mark style="color:blue;">組織設定</mark>」→「<mark style="color:blue;">組織概覽</mark>」，點擊「<mark style="color:blue;">編輯角色權限</mark>」。選擇要設定的角色後，切換至「<mark style="color:blue;">分配技能</mark>」頁籤。
{% endstep %}

{% step %}

### 設定新增技能權限 <a href="#set-create-skill-permission" id="set-create-skill-permission"></a>

依需要勾選或取消「<mark style="color:blue;">允許新增技能</mark>」，決定此角色的成員能否新增技能。變更會立即儲存；成功後畫面會顯示更新成功訊息。
{% endstep %}

{% step %}

### 分配技能 <a href="#assign-skills-to-role" id="assign-skills-to-role"></a>

點擊「<mark style="color:blue;">分配技能</mark>」按鈕，勾選要開放給此角色的技能後確認。
{% endstep %}

{% step %}

### 設定技能權限 <a href="#set-skill-permissions" id="set-skill-permissions"></a>

在已分配清單中，逐一設定每個技能的讀取／編輯／刪除權限，或移除分配。勾選或取消權限後會立即儲存；成功後畫面會顯示更新成功訊息，頁面沒有另外的「儲存」按鈕。
{% endstep %}
{% endstepper %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-3339a4d762b54ab17bd2f31d015b1aae2f3e74b2%2Frole-permission-assign-skills.png?alt=media" alt="角色權限管理的分配技能頁籤，可設定允許新增技能與技能權限"><figcaption><p>在「分配技能」頁籤管理新增權限與個別技能權限</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-9923a16cdc23ef49119db9d307c83b11ef4977e8%2Frole-permission-assign-skills-modal.png?alt=media" alt="分配技能視窗，左側為可選技能，右側為已選技能"><figcaption><p>從可用技能中選擇要分配給角色的技能</p></figcaption></figure>

{% hint style="info" %}
角色的建立與成員分配方式，請參閱 [角色權限管理](/org/roles/role-permission.md)。
{% endhint %}

***

## 刪除技能 <a href="#delete-skill" id="delete-skill"></a>

在技能列表中，點擊該技能的 <mark style="color:blue;">刪除</mark> 圖示，確認後即可刪除。

{% hint style="warning" %}
刪除技能後，已綁定此技能的 Agent 將無法再使用該技能。此操作不可復原。
{% endhint %}


---

# 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/build/skills/skills-management.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.