# Skill 如何執行

Skill 如何被觸發、觸發訊息如何影響它，以及驅動執行的 prompt。

## 觸發路徑

### `/skill-name` slash command

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

```
/code-reviewer review the diff in this PR
```

`runtime.MatchSkill` 在執行啟動時於 `exec.Prepare` 內執行（以名稱傳入的 skill 則改在 `exec.Start` 解析，被排除或找不到時該次執行失敗）。命中時，agenvoy 會直接合成一組 `run_skill` `tool_call` 與對應的 `tool_result` 進 `ToolHistories`。v1.1.0 起該 tool result 承載完整的啟用內容 —— `configs/prompts/assign_skill.md` 的 `BINDING SKILL` 規則、`skill_execution.md`、built-in 工具清單與 skill 內文 —— 且不再另加 system message，因此 system prompt 保持不變、prefix cache 得以保留。Slash 路徑為嚴格執行：每一步都具約束力。SKILL.md 沒有 `ask_user` 步驟時絕不呼叫 `ask_user`；單獨的 `/<skill-name>` 以 skill 預設值從第一步開始執行。

若使用者帶入 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 發起的路徑僅供參考：工具回傳 skill 名稱、目錄與內文作為參考資料，agent 擷取適用的部分，而非逐步執行。`BINDING SKILL` 包裝與 `skill_execution.md` 只套用於 slash 路徑。

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

### 單一對話中的多 skill

一個對話可依序啟用多個 skill。每次啟用都各自成為對話中的一筆 `run_skill` tool result，後啟用的 skill 在 tool 歷史中排在先前的之後；沒有任何一個會寫進 system prompt。

## User message 是 binding context

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

具體而言：

- SKILL.md 描述預設行為
- User message 覆寫或增補預設行為
- 單獨的 slash command 代表採用 skill 預設值；使用者意圖與某步驟衝突時，照步驟執行並在最終輸出說明衝突

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

## Skill 執行 prompt

執行迴圈由 `configs/prompts/skill_execution.md` 驅動，它承載每個 skill 都須遵守的規則（輸出紀律、工具名稱對映、mandatory principle）。v1.1.1 起其中一條是先規劃再執行：三個步驟以上的 Skill 會依本次請求適用的步驟開一份 `write_todo` 清單。

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