---
site: "zyx.tw"
title: "Skill 的載入由模型決定，harness 負責把全文送進對話"
description: "模型靠 name 與 description 選 Skill，harness 再把全文放進對話。"
url: "https://www.zyx.tw/map/basics/how-a-skill-loads"
---

# Skill 的載入由模型決定，harness 負責把全文送進對話

紀錄 058，深讀 L2，907 字，2 分鐘，v1.0.0，更新 2026-11-16

模型決定用哪份 Skill，harness 再把全文放進對話。 harness 是負責掃描檔案、組裝 context 與回傳工具訊息的執行環境。

模型不能直接讀檔或下指令，只能提出要用哪個工具、帶哪些參數的請求。harness 執行後把結果送回對話，這一來一回叫工具呼叫，完整說明見 Agent Loop。

Skill 已說明基本分工。以下以 Claude Code 為例，照發生的先後說明 6 步。

## 第 1、2 步：harness 只讀 2 個欄位並排成清單

Agent Skills 格式以資料夾為單位，內含 SKILL.md，也能放附檔與腳本。Codex、Cursor、Gemini CLI、opencode 也讀同樣格式。

第 1 步：對話開始時，harness 掃描 .claude/skills/\<名稱\>/、~/.claude/skills/\<名稱\>/，以及 Plugin 提供的 Skill。此時只讀檔案開頭的 name 與 description。

以下是 .claude/skills/release-notes/SKILL.md 的內容：

```
---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes, a changelog entry, or 發版說明.
---

# Release notes

1. Run `git log --oneline` for the commits since the last tag.
2. Group them under Added, Changed and Fixed.
3. Write one line per commit, in plain words.
```

第 2 步：harness 把這 2 個欄位排成清單，放進 context。harness 同時指示模型，任務符合時用 Skill 工具載入。

## 第 3、4 步：模型自己選，工具再帶回全文

harness 沒有用關鍵字比對或分類器選 Skill。第 3 步：模型讀清單後自行決定，當下的判斷線索只有 name 與 description。

第 4 步：選定後，模型呼叫 Skill，以名稱作為參數。harness 回傳簡短的工具結果，再加入包含資料夾路徑與全文的新訊息，全文不含開頭的 2 個欄位。

```
模型     tool_use     Skill {"skill": "release-notes"}
harness  tool_result  Launching skill: release-notes
harness  message      Base directory for this skill:
                      .claude/skills/release-notes

                      # Release notes
                      1. Run `git log --oneline` for the commits ...
```

工具呼叫的結構見 工具呼叫的格式。

## 第 5、6 步：全文留在對話，附檔另外讀取

第 5 步：新訊息從此是對話的一部分，之後每一輪都跟著整段對話一起送給模型，直到對話被壓縮。每輪重送的機制見 context 的組成。

第 6 步：全文若提到相對路徑，模型依載入時收到的資料夾路徑定位附檔，再用一般讀檔工具讀取。腳本則由一般指令工具執行，程式碼不進 context，只有輸出進去。

## 依判斷線索與載入成本安排內容

因為第 3 步只看 2 個欄位，所以名稱或說明必須看得出用途。description 要寫適用任務，並包含使用者實際會說的詞與語言，例如「發版說明」。

因為第 2 步會建立清單，所以每多裝 1 份 Skill，每段對話都多 1 組欄位，即使沒有用到。

因為第 5 步會保留訊息，所以全文越長，載入後每輪負擔越大。全文只留步驟，少用的細節放附檔；通則與個案的取捨見 Skill 不寫個案。

## 沒載入時，先查找到沒有，再查選了沒有

用 Claude Code 非互動模式（claude -p），加上 --output-format stream-json --verbose。輸出會把每個事件印成一行 JSON，第 1 個事件的 skills 欄位列出找到的 Skill 名稱。

名稱不在 skills，代表第 1 步沒找到。檢查資料夾位置、檔名是否為 SKILL.md，以及開頭欄位格式；這時改說明沒有用。

名稱在 skills，後面卻沒有名稱為 Skill 的工具呼叫，代表已列出但模型沒選。此時修改 name 或 description，讓用途與適用任務可辨識。

## 地圖

- 先讀：[Agent Loop 讓模型提出請求，由程式執行並送回結果](https://www.zyx.tw/map/harness/agent-loop.md)
- 先讀：[Skill 保存同類任務的做法，個案細節留在專案](https://www.zyx.tw/map/basics/skill-loads-on-demand.md)
- 回到：[基礎](https://www.zyx.tw/map.md)
