# 技能 (/zh-Hant/docs/verdent-manager/core-features/skills)
> 透過可重複使用的知識包擴展 Verdent 的能力，支援專業工作流程與領域專業知識
Verdent **技能（Skills）** 是可重複使用的知識包，能擴展代理的專業能力。每個技能都包含特定領域的提示詞、腳本、參考資料與最佳實務。只要按名稱呼叫技能，代理便會載入對應的上下文並依照預先定義的工作流程執行。
***
## 什麼是技能？ [#什麼是技能]
### 核心概念 [#核心概念]
**技能** 是儲存於資料夾中的結構化知識包。每個技能都包含一個 `SKILL.md` 檔案，用以定義其名稱、描述與詳細提示詞。當你在對話中呼叫某個技能時，Verdent 會讀取此檔案並將其內容注入代理的上下文中。
### 技能與子代理、MCP 的差異 [#技能與子代理mcp-的差異]
| 面向 | 技能 | 子代理 | MCP |
| -------- | ------------------- | ------------------- | ---------------------- |
| **觸發方式** | 透過 `@skill` 或提及手動呼叫 | 由主代理自動產生 | 自動呼叫或明確呼叫 |
| **執行方式** | 擴展主對話的上下文 | 以獨立子任務形式執行，具有隔離的上下文 | 透過 JSON-RPC 2.0 呼叫外部工具 |
| **用途** | 領域指引（例如「如何撰寫測試」） | 獨立操作（例如「執行程式碼審查」） | 存取外部資料／工具（例如資料庫查詢） |
| **生命週期** | 一次性上下文注入 | 完成子任務後回傳結果 | 工作階段期間持續運行的伺服器程序 |
| **實作方式** | Markdown 檔案 + 可選腳本 | 內建代理邏輯 | 可執行的伺服器程序 |
簡而言之：**技能提供知識與工作流程指引**、**子代理執行獨立任務**、**MCP 連接外部工具與資料來源**。
***
## 如何使用技能 [#如何使用技能]
### 呼叫技能 [#呼叫技能]
你可以透過兩種方式呼叫技能：
**1. 在對話中提及技能名稱**
```
Use the skill-creator skill to help me create a new Skill
```
**2. 使用 @ 提及語法**
```
@skill-creator help me create a Skill for API documentation generation
```
當技能被觸發時：
1. 代理會呼叫 `skill` 工具來讀取技能的 `SKILL.md` 檔案
2. 檔案內容會被注入目前的對話上下文
3. 代理依照技能的指引繼續工作
### 瀏覽可用技能 [#瀏覽可用技能]
透過設定存取技能面板：
1. 開啟 **Settings** 選單
2. 選擇 **Skills** 分頁
3. 瀏覽已安裝的技能與技能商店中的可用技能
你也可以在輸入框中輸入 `@` 來觸發自動完成，並快速選取可用技能。
***
## 內建技能 [#內建技能]
Verdent 內建一組技能，涵蓋常見的工作流程：
| 技能 | 描述 |
| ------------------- | -------------------------------------- |
| **docx** | 讀取、建立或編輯 Word 文件（`.docx`），並進行格式忠實的視覺檢查 |
| **find-skills** | 探索並安裝技能——當你詢問「我該如何做某件事？」或尋找新能力時使用 |
| **frontend-design** | 建立具有高設計品質、獨特且達到生產等級的前端介面 |
| **pdf** | 透過視覺渲染與內容擷取，讀取、建立或審閱 PDF 檔案 |
| **pptx** | 讀取、建立或編輯 PowerPoint 簡報（`.pptx`） |
| **skill-creator** | 用於建立並迭代自訂技能的引導式工作流程 |
| **xlsx** | 讀取、分析、視覺化並智慧編輯 Excel 試算表 |
**技能商店** 中還有更多技能可用。開啟 **Settings → Skills → Store** 即可瀏覽並安裝其他技能。
***
## 建立自訂技能 [#建立自訂技能]
你可以建立自訂技能，封裝團隊的領域專業知識或專案特定的工作流程。
### 技能目錄結構 [#技能目錄結構]
標準的技能資料夾結構如下：
```
my-custom-skill/
├── SKILL.md # Required: Skill definition file
├── agents/
│ └── verdent.yaml # Optional: UI configuration (icons, display name)
├── scripts/ # Optional: helper scripts
└── references/ # Optional: reference docs or examples
```
### SKILL.md 格式 [#skillmd-格式]
`SKILL.md` 是技能的核心檔案，包含 YAML frontmatter 與 Markdown 主體：
```markdown
---
name: my-custom-skill
description: A concise description shown in the Skill list
metadata:
version: "1.0.0"
author: "Your Name"
license: "MIT"
---
# Detailed Instructions
This is the detailed prompt content the Agent reads.
## Workflow
1. Step one
2. Step two
3. ...
## Best Practices
- Practice suggestion 1
- Practice suggestion 2
```
**Frontmatter 欄位需求：**
* `name`（必填）：必須與資料夾名稱相符。僅允許小寫字母、數字與連字號（`a-z0-9-`）。長度為 1–64 個字元。不可有連續連字號，也不可以連字號開頭或結尾。
* `description`（必填）：簡短描述，最多 1024 個字元。
* `metadata`（選填）：版本、作者、授權及其他中繼資訊。
### 安裝自訂技能 [#安裝自訂技能]
**方法 1：透過設定匯入**
1. 開啟 **Settings → Skills**
2. 點選 **Import Skill**
3. 選擇技能資料夾（或 `.zip` / `.skill` 壓縮檔）
4. Verdent 會驗證 `SKILL.md` 並將其安裝至 `~/.verdent/skills/`
**方法 2：手動複製**
```bash
cp -r my-custom-skill ~/.verdent/skills/
```
重新啟動 Verdent 或重新整理技能清單後，該技能即可使用。
**方法 3：專案層級技能**
將技能放置於你的專案目錄內：
```bash
cp -r my-custom-skill /path/to/your/project/.verdent/skills/
```
專案層級技能僅在該專案內可見，且在同名情況下優先於全域技能。
***
## 技能範圍 [#技能範圍]
Verdent 支援三種層級的技能範圍：
| 層級 | 位置 | 可見範圍 |
| ------ | ---------------------------- | ---------- |
| **全域** | `~/.verdent/skills/` | 所有專案與工作區 |
| **專案** | `/.verdent/skills/` | 僅限目前專案的工作區 |
**優先順序規則：**
當多個範圍存在同名技能時：
* 專案會覆寫全域
***
## 技能商店 [#技能商店]
Verdent 提供 **技能商店**，供你瀏覽並安裝社群與官方技能。
### 瀏覽技能商店 [#瀏覽技能商店]
1. 開啟 **Settings → Skills**
2. 切換至 **Store** 分頁
3. 瀏覽可用技能或使用搜尋框
### 從商店安裝 [#從商店安裝]
1. 在商店中找到想要的技能
2. 點選 **Install**
3. 技能會自動下載並安裝至 `~/.verdent/skills/`
**安全驗證：**
從商店安裝的技能會經過 SHA256 校驗碼驗證，以確保檔案完整性與安全性。
***
## 實際範例 [#實際範例]
### 範例 1：使用 `skill-creator` 建立新技能 [#範例-1使用-skill-creator-建立新技能]
```
@skill-creator help me create a Skill for guiding the team on writing Go unit tests
```
代理將會：
1. 讀取 `skill-creator` 技能內容
2. 引導你填寫技能名稱、描述與核心提示詞
3. 產生標準的 `SKILL.md`
4. 建議安裝路徑與驗證步驟
### 範例 2：使用 `spreadsheet` 分析資料 [#範例-2使用-spreadsheet-分析資料]
```
@spreadsheet read sales-2025.xlsx from the project root, analyze Q1 sales trends, and generate a chart
```
代理將會：
1. 載入 `spreadsheet` 技能
2. 使用 `pandas` 與 `openpyxl` 讀取 Excel 檔案
3. 分析資料並產生視覺化結果
4. 儲存結果或在對話中顯示
### 範例 3：使用 `gh-fix-ci` 修復 CI [#範例-3使用-gh-fix-ci-修復-ci]
```
@gh-fix-ci my PR #123 GitHub Actions tests are failing, help me debug
```
代理將會：
1. 使用 `gh` CLI 取得 PR #123 的 CI 日誌
2. 分析失敗原因（例如測試案例錯誤、相依問題）
3. 提出修復方案
4. 在你核准後修改程式碼並推送修復
***
## 常見問題 [#常見問題]
當技能被呼叫時，代理會讀取 `SKILL.md` 檔案，這會計入 token 用量，因此會消耗點數。不過技能本身不會發出額外的 API 呼叫。
可以。將技能安裝至 `~/.verdent/skills/`（全域範圍），它便會在所有專案中可用。
在 **Settings → Skills** 中右鍵點選該技能並選擇 **Delete**。標記為 `undeletable` 的內建技能無法刪除，並會在下次啟動時重新安裝。
可以。Verdent 會自動偵測 `~/.cursor/skills`、`~/.claude/skills` 與 `~/.codex/skills` 中的技能，並提示你匯入。在 **Settings → Skills** 中點選 **Import from External Sources**。
* **專案規則**：永遠啟用的指令，會自動注入每一次對話
* **技能**：按需注入的知識包，僅在被呼叫時注入
通用的程式碼規範請使用規則；特定領域的工作流程請使用技能。
從技能商店安裝的技能會在背景自動檢查更新。手動安裝的技能則需要重新匯入（覆寫舊版本）以進行更新。
***
## 進階用法 [#進階用法]
### 在技能中嵌入腳本 [#在技能中嵌入腳本]
在你的技能中新增 `scripts/` 目錄，並在 `SKILL.md` 中參照這些腳本：
```markdown
## Data Processing Script
Run the following command to process data:
\`\`\`bash
python scripts/process_data.py --input data.csv --output results.json
\`\`\`
```
代理會讀取此指令並在需要時執行腳本。
### 參照文件 [#參照文件]
將 API 文件、規格或範例程式碼存放於 `references/` 目錄中，並在 `SKILL.md` 中加以連結：
```markdown
## Reference Documentation
See [references/api-spec.md](references/api-spec.md) for the detailed API specification.
```
代理可依照技能的指引讀取這些參考檔案。
***
## 最佳實務 [#最佳實務]
**保持技能聚焦。** 每個技能都應針對單一領域或工作流程。避免建立「萬能」技能——應將其拆分為更小、更專精的技能。
**使用清晰的命名。** 技能名稱應簡潔且具描述性，例如 `api-doc-generator` 而非 `my-skill-1`。
**提供範例與參考資料。** 在 `SKILL.md` 中加入具體範例與參考連結，協助代理更好地理解預期的輸出。
**維護版本號。** 使用 `metadata.version` 欄位來追蹤更新與相容性。
**分享前先測試。** 在推廣給團隊或發布至技能商店之前，先於測試專案中驗證你的技能。
***
## 另請參閱 [#另請參閱]
子代理的運作方式以及如何管理它們
透過 MCP 連接外部工具與服務
設定永遠啟用的專案規則與使用者規則
透過內建的審查器審查程式碼變更