第五章　文件格式與協議

本章覆蓋第 21–24 章：SKILL.md 格式、資料與備份、文件命名慣例與設置匯出格式。

第二十一節技能（SKILL.md）格式

[!ref] 詳解見使用者手冊「技能（Skill）系統」節。

21.1 文件結構

<skill-root>/
├── SKILL.md              # 必需。前置元資料 + 模板本文
├── README.md             # 可選。給人看的說明
├── examples/             # 可選。範例輸入輸出
└── …                     # 可選附加資源

21.2 前置元資料欄位

SKILL.md 頂部使用 --- 分隔的 YAML 前置元資料，所有可識別欄位：

欄位	類型	必填	說明
`name`	string	✓	用作 slash 名（建議小寫連字元）
`description`	string	✓	一句話說明，列在 `/help` 中
`argument-hint`	string		`<arg1> <arg2>` 提示
`allowed-tools`	array		限制本技能可用的工具白名單
`denied-tools`	array		黑名單（與白名單二選一）
`work-modes`	array		適用工作模式 `[plan, execute, …]`
`model`	string		強制使用的模型；缺省繼承當前
`temperature`	number		強制溫度；缺省繼承當前
`version`	string		語義化版本號
`license`	string		SPDX 識別
`author`	string		作者 / 團隊
`tags`	array		用於市場過濾
`signature`	string		國密簽章塊（由簽章工具自動寫入）

21.3 本文模板

本文為標準 Markdown，支持下列擴充：

語法	含義
`$1` `$2` `$N`	第 N 個位置參數
`$ARGUMENTS`	全部參數原樣拼接
!`<shell>`	Shell 預處理；輸出取代該位置
`{{include:path}}`	內聯另一個 Markdown 文件（相對 skill-root）

21.4 三層載入優先級

層級	路徑	優先級
全域	應用資料目錄的全域技能區	最低
工作區	`<workspace>/.config/skills/<name>/`	中
外掛	外掛包內提供	高

21.5 呼叫方式

方式	觸發點	行為
使用者 slash	`/<name> <args>`	渲染後注入下一回合 system prompt
助手主動	`skill.invoke` 工具	渲染後作為工具回應回到對話流

21.6 內置技能

內置技能（如 skill-creator）啟動時自動物化、內容漂移自動覆蓋。
構建期簽章 + 內置簽章錨點（trust ExtraSignerRoots），嚴格簽章政策下也放行。
設置 → 技能 面板以「內置」徽標區分內置 / 自建 / 第三方。
相容 Agent Skills（agentskills.io）：跨用戶端發現 / 解析容錯 + 工具名翻譯映射。

21.7 `market.check`（發佈契約校驗）

內置只讀、確定性、離線工具，按 zMarket 發佈契約校驗本機技能 / 外掛目錄：

參數	類型	預設	說明
`path`	string	—	必填，待校驗目錄相對路徑（如 `.avlcode/skills/my-skill`）
`kind`	string	自動探測	`skill` / `plugin` / `mcp` / `provider`
`version`	string	目錄推斷	覆蓋 / 補充嚴格 semver
`source`	string	`./<name>`	覆蓋 source 形態
`manifest`	string	從目錄派生	直接給 manifest JSON

報告過 / 不過 + 原因 + 缺什麼（name slug、嚴格 semver、source 形態、能力聲明、歸檔安全等）。不連網、不提交。注：.skill-sign 簽章 ≠ zMarket 認可；只查發佈契約形態，非執行階段安全稽核。

第五章 文件格式與協議

第二十一節 技能（SKILL.md）格式