Lab／Session 10

用 Markdown 寫 Skill

把一份標註規範，寫成模型讀得懂、也找得到的文件。

時長約 100 分鐘先備無；會用文字編輯器即可產出一份可載入的標註技能與觸發測試集

《論語．學而》

學而時習之，不亦說乎？
有朋自遠方來，不亦樂乎？

一段寫給模型的指示

幫我標隱喻先通讀全文再切詞每個詞查基本義如果語境義和基本義不同就標MRW像如好比這些詞標MFlag最後輸出表格## 標註程序
1. 通讀全文
2. 切分詞彙單位
3. 查基本義，與語境義比較
4. 兩者有別即標 `MRW`
5. 「像、如、好比」標 `MFlag`

《禮記．學記》說入學一年要考「離經辨志」，離經就是斷句。字沒有變，結構一旦標出來，讀的人就知道哪裡停、哪裡接、哪些話是同一件事。Markdown 對一份技能文件做的，正是這件事。

0:00

為什麼是 Markdown

0:10

九個符號

0:30

技能的解剖

0:50

description

1:05

動手寫

1:35

驗證與互評

一、為什麼是 Markdown

一個代理系統裡流動的語言，大致分成三層：自然語言負責意義與協商，JSON 一類的結構化資料負責狀態與工具呼叫，Markdown 則是人和模型共用的工作空間，計畫、報告、記憶與技能檔都寫在這一層（Hsieh 2026，表 1）。一份 SKILL.md 剛好跨了三層：開頭是 YAML，主體是 Markdown，Markdown 裡裝的是自然語言。

層	在 SKILL.md 裡	擅長	主要風險
結構化資料	frontmatter：`name`、`description`	機器可驗證	格式一錯，整份技能載入失敗
半結構文本	標題、清單、表格、程式碼區塊	人可讀，模型可定位	過時或互相衝突的指示
自然語言	每一條規則的內容	表達理由與例外	歧義、說得不夠

有一點常被忽略：模型從來沒有「看到」排版後的 Markdown。## 和 | 對它而言只是詞元，和其他文字一起進入同一條序列。這些符號之所以有用，是因為預訓練語料裡滿是 README、技術文件與筆記，模型早已學會「## 之後是新話題」「1. 之後的東西有順序」這些文類慣例。切換下面的檢視，比較兩種讀者看到的東西。

語言學視角：標記即後設語篇

Hyland（2005）把「首先、總之、如下表所示」這類組織篇章、引導讀者的語言稱為後設語篇（metadiscourse）。Markdown 標記是後設語篇的符號化版本：## 宣告話題轉換，1. 宣告程序，表格宣告「以下各項可以逐欄比較」。對人類讀者，它們在版面上顯現；對模型，它們以詞元的身分參與預測。

二、九個符號

寫技能只需要九種標記，外加檔頭的 YAML。右欄是每一種在技能裡的典型用途；用錯地方的代價，第七節會再談。

標記	寫法	在技能裡用來
標題	`# 標題` `## 小節`	切出話題。一份技能只有一個 `#`，其下用 `##`，不跳級
編號清單	`1. 第一步`	有先後順序的程序
項目清單	`- 一項`	沒有順序的並列條件、例子
粗體	`重點`	一段裡最不能漏看的詞，少用
行內程式碼	`MRW`	標籤名、檔名、必須逐字照寫的字串
程式碼區塊	```markdown … ```	輸出樣板。區塊裡的東西照抄，不詮釋
表格	`\| 標籤 \| 定義 \|`	標籤集：每個標籤的名稱、定義、例子並排比較
連結	`[說明](references/a.md)`	指向參考檔；技能裡也常直接寫路徑
引用	`> 原文`	引述語料或使用者原話，與指示分開
frontmatter	`---` 包住的 YAML	放 `name` 與 `description`，只能出現在檔案最開頭

即時編輯器

下面是一份寫壞了的言語行為標註技能。左邊改原始碼，右邊同步顯示排版結果、文件大綱與三層檢查。完成下列五項，任務清單會自動打勾。

修正標題跳級：「步驟」不該是四級標題。
把步驟那一段改寫成編號清單。
把用粗體排出來的兩個標籤，改成一張「標籤、定義、例子」表格。
把輸出格式的表格圍進 ```markdown 程式碼區塊。
補完 description：做什麼、何時用、何時不用。

SKILL.md 原始碼

排版結果

三、評點一份 SKILL.md

明清評點家在書頁旁以朱筆批註，指出某句為何要緊、某處如何呼應。下面用同樣的方式讀起手包裡的範例技能 mipvu-zh（簡化版 MIPVU 隱喻標註）。每段批註依它處理的層次著色，可以只看其中一層。

句法：格式與規格語意：程序與定義語用：何時用、何時讀

完整檔案在起手包的 mipvu-zh/SKILL.md，參考檔在同資料夾的 references/。

語言學視角：工具與技能的三層

Hsieh（2026）把工具呼叫拆成三層：綱要是句法，說明是語意，何時呼叫是語用。技能沿用同一個切分。frontmatter 的格式是句法；程序與標籤定義是語意；description 與「什麼時候去讀哪個參考檔」則是語用，因為它們規定的是一段文字在什麼情境下生效。

四、三層載入

想像一面書架。找資料時你先掃書背，只抽出看起來相關的那本；翻開後讀目錄與序，需要細節時才翻到附錄。技能的載入方式相同，稱為漸進揭露（progressive disclosure）：所有技能的 name 與 description 一開始就在模型的脈絡裡，內文在觸發後才讀，參考檔則等內文指引時才讀。

點選下面三則使用者請求，看每一則會讓哪幾層進入脈絡。

一

書背：name 與 description

每個技能約百來個詞元，所有技能同時在場。模型只憑這一層決定要不要抽出某本書。

frontmatter

二

目錄與序：SKILL.md 內文

觸發後才讀入。規格建議控制在 500 行以內，長篇細則往下一層放。

SKILL.md 的 frontmatter 之後

三

附錄：references/、scripts/

內文寫明「遇到某情況讀某檔」，模型才會去讀。沒有被指向的檔案，等於不存在。

references/guideline.md、references/examples.md

先點選一則請求。

五、description 是語用

description 的語力是一個條件式指令：「當情境符合 X，就讀我」。它是否生效，取決於模型能不能從使用者的話認出 X。這和 Searle 所說的預備條件同構：請求要成立，聽者得有能力、情境得合適；技能要觸發，使用者的請求得落在 description 描述的情境裡，而且模型得認得出來。

觸發失敗有兩種方向，正好對應 Grice 的量的準則。說得太少，技能在該出場時沒出場（觸發不足）；說得太多或太寬，鄰近任務也把它叫出來（誤觸發）。現行模型比較常犯前者，所以 description 寧可主動一點，寫出使用者實際會用的說法。

三句式

做什麼：一句話說清楚任務與產出。
何時用：列出使用者會怎麼說，並加上「即使對方沒有提到某某術語」。
何時不用：點名最容易混淆的鄰近任務。

練習：它會不會觸發？

以下是 mipvu-zh 的 description。讀完後判斷每一則請求是否應該讓它觸發。

六、動手寫

W06 的課堂問題是：寫 prompt 比較像下指令、寫規格，還是教一個新來的助理？寫一份標註技能，三者都有。請以你熟悉的一種語言學標註為題，例如言語行為、量詞、詞義、語碼轉換、評價語言，寫出一份技能。左邊填表，右邊即時產生 SKILL.md 並做三層檢查。表單已預先填入一份言語行為標註的範例，可以直接改寫，也可以清空重來。

frontmatter

name小寫英文、數字、連字號；也是資料夾名稱

做什麼description 第一句

何時用第二句，寫使用者會怎麼說

何時不用第三句，點名鄰近任務

內文

標題

為什麼要照這套程序做一兩句

何時使用每行一項

標籤集名稱、定義、例子

標註程序每行一步，會自動編號

輸出格式樣板會自動圍進程式碼區塊

邊界案例每行一項

產生的 SKILL.md

三層檢查

產生器只能寫出單一檔案。需要參考檔時，下載後在資料夾裡另建 references/，並在內文寫明何時去讀。

七、七種常見失誤

以下每一項都來自真實的技能草稿。點開比較改寫前後。

八、用 Python 驗證

起手包附兩支程式。skill_lint.py 做的檢查和本頁相同，適合寫完後在本機跑一次；trigger_eval.py 才是真正的試金石：它把你的技能和幾個鄰居技能並列，對每一則測試請求問模型要讀哪一個，重複數次後計算觸發率。

# 1. 格式與結構
$ python tools/skill_lint.py mipvu-zh

【句法】
  ✓ frontmatter 符合規格
【語意】
  ✓ 內文結構完整：標題、程序、標籤表、輸出樣板都在
【語用】
  ✓ description 同時說明了做什麼、何時用、何時不用

# 2. 觸發測試（先用 --dry-run 檢查提示，不需金鑰）
$ python tools/trigger_eval.py tools/evals/mipvu-zh.triggers.json --runs 3

觸發測試的結果用精確率與召回率解讀，兩者剛好對應上一節的兩種失敗：

指標	問的是	偏低代表	改寫方向
召回率	該觸發的請求，有幾成真的觸發	觸發不足	在「何時用」補上使用者的實際說法
精確率	觸發的請求，有幾成是該觸發的	誤觸發	在「何時不用」點名被誤叫出來的鄰近任務

測試集的設計比程式本身重要。最有診斷力的負例不是「今天天氣如何」，而是和你的任務共享詞彙的鄰近任務：同樣談「比喻」的文案寫作、同樣處理中文的斷詞、同樣做標註的情感分析。起手包的 mipvu-zh.triggers.json 示範了這種設計。

語言學視角：description 是一條釋義

寫 description 很像編詞典。釋義太窄，合法的用例被排除；太寬，不相干的用例被收進來。召回率與精確率，正是詞典學家檢驗釋義時心裡那兩把尺。差別在於，詞典的讀者是人，會用常識補足釋義的缺口；description 的讀者是模型，它補缺口的方式由訓練資料決定，所以必須實際測試，不能只靠自己讀起來覺得清楚。

程式說明見起手包的 README.md。測試結果是近似值：真實環境裡模型在更完整的脈絡下決定是否讀取技能。

九、繳交與討論

繳交內容

一個以 name 命名的資料夾，內含 SKILL.md；有參考檔就放進 references/。
skill_lint.py 的輸出：句法層沒有 ✗。
一份觸發測試集，至少 10 則請求，其中至少 4 則是不應觸發的鄰近任務。
至少一輪 trigger_eval.py 的結果，以及你根據結果改寫 description 前後的對照。
一段約 200 字的反思：寫給模型的規範，哪些地方必須比寫給人類標註員的更明確？

課堂互評（最後 15 分鐘）

兩人一組交換技能，只讀對方的 description，不看內文，寫下你猜這份技能會做什麼、產出長什麼樣子。再打開內文核對。猜錯的地方，就是 description 沒有說到的地方。

討論

標註規範原本寫給人類標註員。改寫給模型時，你補上了哪些原本隱含的知識？這說明人類標註一致性的來源有哪些不在規範裡？
Markdown 標記對模型而言只是詞元。它的作用比較像句讀、像文類慣例，還是像程式語法？三種說法各自預測什麼現象？
一份技能是不是言語行為？如果是，它的語力在何時生效：寫下時、載入時，還是被觸發時？
description 和詞典釋義都在劃定使用範圍。原型理論對詞義的批評，是否也適用於 description？