Skill 的載入由模型決定,harness 負責把全文送進對話
深讀 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,讓用途與適用任務可辨識。