文件 v0.30.0
首頁 GitHub

Skill 系統

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

Skill 格式

Skill 是一個帶有 YAML frontmatter 作為 metadata 的 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 啟用時 render 進 system prompt。

觸發路徑

/skill-name slash command

在任何輸入前加上 /<skill-name>：

/code-reviewer review the diff in this PR

當 MatchSkillCall 命中時，agenvoy 會直接合成一組 run_skill tool_call 與對應的 tool_result（內含 skill 內文）進 ToolHistories — 與自然語言啟用路徑逐位元相同，保留 prefix cache。

若使用者帶入 args（/code-reviewer review src/parser.go），user message 會剝除 /<skill-name> prefix，只留下 args。若無 args，user message 保留字面的 /<skill-name>，讓 LLM 仍能看到啟用 context。

自然語言啟用

若 agent 在執行中判定某任務需要 skill，它會直接呼叫 run_skill。這是 LLM 發起的路徑，並使用相同的 render pipeline。

Skill 啟用被設計為工具呼叫（lazy load），而非啟動時的預先挑選 — 這避免了為不需要 skill 的任務付出 skill 內文的 token。

單一對話中的多 skill

一個對話可依序啟用多個 skill。每次 run_skill 呼叫都會 append 至現有的指令堆疊；後續 skill 透過 system-prompt 區塊排序來增補或覆寫先前的 skill。

User message 是 binding context

skill_execution.md Mandatory Principle #5：觸發 skill 的 user message 是 binding context，而非雜訊。LLM 將其視為使用者提供的參數／提示，並編織進輸出。

具體而言：

範例：/readme-generate private MIT — SKILL.md 定義 README 結構；user message 指定 private mode + MIT license，兩者皆覆寫預設值。

Skill 位置

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

路徑 來源標籤
<cwd>/.skills local
<cwd>/.claude/skills claude
~/.config/agenvoy/skills/.system system（內建，由 make build 從 extensions/skills/ 刷新）
~/.config/agenvoy/skills 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 則按需載入內容。

Always-allow 清單

Skill 可被標為 always-allow，使其 tool call 跳過 confirm gate：TUI /dangerous allow-skill，或 POST /v1/allowlist/skill 搭配 scope=global|project。全域項目位於 ~/.config/agenvoy/allow_skill，專案項目位於 <專案>/.agenvoy/allow_skill，載入時取聯集。

Skill 執行 prompt

執行迴圈由 configs/prompts/skill_execution.md 驅動，它承載每個 skill 都須遵守的規則（輸出紀律、工具名稱對映、mandatory principle）。

工具名稱對映範例：為 Anthropic SDK 撰寫的外部 skill 可能引用 AskUserQuestion；agenvoy 透過 skill_execution.md 中的 Tool Name Mapping 表自動將其對映至 ask_user。無需在 Go 端註冊 alias。

EN