# Skill 系統

Skill 是可載入的 markdown 指令包，能將 agent 切換至特定執行模式（例如 commit message 生成、code review、README 生成）。

## Skill 格式

Skill 是一個帶有 YAML frontmatter 作為 metadata 的 markdown 檔案：

```markdown
***
name: code-reviewer
description: Deep code review covering quality, security, and architecture
version: 1.0.0
***

You are now a strict code reviewer...
```

Frontmatter 的 `name` 是觸發關鍵字。skill 啟用時內文以 `run_skill` 的 tool result 送達；v1.1.0 起不再附加進 system prompt。

## Skill 位置

掃描器會走訪九個目錄，因此為其他 agent 撰寫的 skill 無需轉換即可載入：

| 路徑 | 來源標籤 |
|---|---|
| `<cwd>/.skills` | `local` |
| `<cwd>/.claude/skills` | `claude` |
| `~/.config/agenvoy/skills/.system` | `system`（內建，由 `make build` 從 `extensions/skills/` 刷新） |
| `~/.config/agenvoy/skills/.system_design` | `system`（以 `/skill` → `system` 安裝的選用 skill，v1.0.17 起） |
| `~/.config/agenvoy/skills` | `user`（v1.0.22 之前為 `agenvoy`） |
| `~/.claude/skills` | `claude` |
| `~/.codex/skills` | `codex` |
| `~/.opencode/skills` | `opencode` |
| `~/.openai/skills` | `openai` |

每個 skill 是一個包含 `SKILL.md` 以及可選腳本 / 範本的目錄。來源標籤會顯示在 TUI 斜線選單的 skill 旁，一眼看出 `/code-reviewer` 來自本專案、Agenvoy 自身儲存，還是其他 agent 的設定。

System prompt 的 `## Skills` 區塊列出可用項目；`run_skill` 則按需載入內容。

## 內建與可安裝的 skill

內建 skill 為 `extension-install`、`extension-upload`、`scheduler-skill-creator` 與 `skill-creator`。v1.0.17 將 `code-reviewer`、`commit-generate`、`readme-generate`、`version-generate` 與 `search-suitable-public-api` 移出內建。除 `search-suitable-public-api` 外，這些 skill 加上 `wiki-generate` 與（v1.0.21 起）`go-test-generate`、`seo-optimize` 都能在 TUI 以 `/skill` → `system`（v1.0.22 之前為 `/skills`）安裝：這是一個多選清單，勾選的項目會從 `github.com/agenvoy/skill-<name>` 以淺層 clone 到 `~/.config/agenvoy/skills/.system_design/`，已存在但取消勾選的項目則會被刪除，完成後 scanner 會重新掃描。與 `.system` 相同，這些目錄無法透過 `DELETE /v1/skill` 刪除。

## Always-allow 清單

Skill 可被標為 always-allow，使其 tool call 跳過 confirm gate：TUI `/skill` → `permission`，僅限全域範圍（v1.0.22 取代 `/allow-skill`；`/dangerous` 指令更早已移除），或 `POST /v1/allowlist` 帶 `{skill: {name, scope, work_dir}}` 區塊（`scope=global|project`）。全域項目位於 `~/.config/agenvoy/allow_skill`，專案項目位於 `<專案>/.agenvoy/allow_skill`，載入時取聯集。