技能
透過可重複使用的知識包擴展 Verdent 的能力，支援專業工作流程與領域專業知識
Verdent 技能（Skills） 是可重複使用的知識包，能擴展代理的專業能力。每個技能都包含特定領域的提示詞、腳本、參考資料與最佳實務。只要按名稱呼叫技能，代理便會載入對應的上下文並依照預先定義的工作流程執行。
什麼是技能？
核心概念
技能 是儲存於資料夾中的結構化知識包。每個技能都包含一個 SKILL.md 檔案，用以定義其名稱、描述與詳細提示詞。當你在對話中呼叫某個技能時，Verdent 會讀取此檔案並將其內容注入代理的上下文中。
技能與子代理、MCP 的差異
| 面向 | 技能 | 子代理 | MCP |
|---|---|---|---|
| 觸發方式 | 透過 @skill 或提及手動呼叫 | 由主代理自動產生 | 自動呼叫或明確呼叫 |
| 執行方式 | 擴展主對話的上下文 | 以獨立子任務形式執行，具有隔離的上下文 | 透過 JSON-RPC 2.0 呼叫外部工具 |
| 用途 | 領域指引（例如「如何撰寫測試」） | 獨立操作（例如「執行程式碼審查」） | 存取外部資料／工具（例如資料庫查詢） |
| 生命週期 | 一次性上下文注入 | 完成子任務後回傳結果 | 工作階段期間持續運行的伺服器程序 |
| 實作方式 | Markdown 檔案 + 可選腳本 | 內建代理邏輯 | 可執行的伺服器程序 |
簡而言之：技能提供知識與工作流程指引、子代理執行獨立任務、MCP 連接外部工具與資料來源。
如何使用技能
呼叫技能
你可以透過兩種方式呼叫技能：
1. 在對話中提及技能名稱
Use the skill-creator skill to help me create a new Skill2. 使用 @ 提及語法
@skill-creator help me create a Skill for API documentation generation當技能被觸發時：
- 代理會呼叫
skill工具來讀取技能的SKILL.md檔案 - 檔案內容會被注入目前的對話上下文
- 代理依照技能的指引繼續工作
瀏覽可用技能
透過設定存取技能面板：
- 開啟 Settings 選單
- 選擇 Skills 分頁
- 瀏覽已安裝的技能與技能商店中的可用技能
你也可以在輸入框中輸入 @ 來觸發自動完成，並快速選取可用技能。
內建技能
Verdent 內建一組技能，涵蓋常見的工作流程：
| 技能 | 描述 |
|---|---|
| docx | 讀取、建立或編輯 Word 文件（.docx），並進行格式忠實的視覺檢查 |
| find-skills | 探索並安裝技能——當你詢問「我該如何做某件事？」或尋找新能力時使用 |
| frontend-design | 建立具有高設計品質、獨特且達到生產等級的前端介面 |
| 透過視覺渲染與內容擷取，讀取、建立或審閱 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 examplesSKILL.md 格式
SKILL.md 是技能的核心檔案，包含 YAML frontmatter 與 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 2Frontmatter 欄位需求：
name（必填）：必須與資料夾名稱相符。僅允許小寫字母、數字與連字號（a-z0-9-）。長度為 1–64 個字元。不可有連續連字號，也不可以連字號開頭或結尾。description（必填）：簡短描述，最多 1024 個字元。metadata（選填）：版本、作者、授權及其他中繼資訊。
安裝自訂技能
方法 1：透過設定匯入
- 開啟 Settings → Skills
- 點選 Import Skill
- 選擇技能資料夾（或
.zip/.skill壓縮檔） - Verdent 會驗證
SKILL.md並將其安裝至~/.verdent/skills/
方法 2：手動複製
cp -r my-custom-skill ~/.verdent/skills/重新啟動 Verdent 或重新整理技能清單後，該技能即可使用。
方法 3：專案層級技能
將技能放置於你的專案目錄內：
cp -r my-custom-skill /path/to/your/project/.verdent/skills/專案層級技能僅在該專案內可見，且在同名情況下優先於全域技能。
技能範圍
Verdent 支援三種層級的技能範圍：
| 層級 | 位置 | 可見範圍 |
|---|---|---|
| 全域 | ~/.verdent/skills/ | 所有專案與工作區 |
| 專案 | <project>/.verdent/skills/ | 僅限目前專案的工作區 |
優先順序規則：
當多個範圍存在同名技能時：
- 專案會覆寫全域
技能商店
Verdent 提供 技能商店，供你瀏覽並安裝社群與官方技能。
瀏覽技能商店
- 開啟 Settings → Skills
- 切換至 Store 分頁
- 瀏覽可用技能或使用搜尋框
從商店安裝
- 在商店中找到想要的技能
- 點選 Install
- 技能會自動下載並安裝至
~/.verdent/skills/
安全驗證：
從商店安裝的技能會經過 SHA256 校驗碼驗證，以確保檔案完整性與安全性。
實際範例
範例 1：使用 skill-creator 建立新技能
@skill-creator help me create a Skill for guiding the team on writing Go unit tests代理將會：
- 讀取
skill-creator技能內容 - 引導你填寫技能名稱、描述與核心提示詞
- 產生標準的
SKILL.md - 建議安裝路徑與驗證步驟
範例 2：使用 spreadsheet 分析資料
@spreadsheet read sales-2025.xlsx from the project root, analyze Q1 sales trends, and generate a chart代理將會：
- 載入
spreadsheet技能 - 使用
pandas與openpyxl讀取 Excel 檔案 - 分析資料並產生視覺化結果
- 儲存結果或在對話中顯示
範例 3：使用 gh-fix-ci 修復 CI
@gh-fix-ci my PR #123 GitHub Actions tests are failing, help me debug代理將會：
- 使用
ghCLI 取得 PR #123 的 CI 日誌 - 分析失敗原因（例如測試案例錯誤、相依問題）
- 提出修復方案
- 在你核准後修改程式碼並推送修復
常見問題
技能會消耗點數嗎？
當技能被呼叫時，代理會讀取 SKILL.md 檔案，這會計入 token 用量，因此會消耗點數。不過技能本身不會發出額外的 API 呼叫。
我可以跨專案共用自訂技能嗎？
可以。將技能安裝至 ~/.verdent/skills/（全域範圍），它便會在所有專案中可用。
我該如何刪除不再需要的技能？
在 Settings → Skills 中右鍵點選該技能並選擇 Delete。標記為 undeletable 的內建技能無法刪除，並會在下次啟動時重新安裝。
我可以從 Cursor、Claude Desktop 或 Codex 匯入技能嗎？
可以。Verdent 會自動偵測 ~/.cursor/skills、~/.claude/skills 與 ~/.codex/skills 中的技能，並提示你匯入。在 Settings → Skills 中點選 Import from External Sources。
技能與專案規則有什麼不同？
- 專案規則：永遠啟用的指令，會自動注入每一次對話
- 技能：按需注入的知識包，僅在被呼叫時注入
通用的程式碼規範請使用規則；特定領域的工作流程請使用技能。
我該如何更新已安裝的技能？
從技能商店安裝的技能會在背景自動檢查更新。手動安裝的技能則需要重新匯入（覆寫舊版本）以進行更新。
進階用法
在技能中嵌入腳本
在你的技能中新增 scripts/ 目錄，並在 SKILL.md 中參照這些腳本：
## 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 中加以連結：
## 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 欄位來追蹤更新與相容性。
分享前先測試。 在推廣給團隊或發布至技能商店之前，先於測試專案中驗證你的技能。