高效 AI 駕馭術
Skill 怎麼寫?SKILL.md 寫法、觸發條件與範例,Claude Code 和 Codex 共用(2026)
什麼樣的重複工作值得寫成 skill、description 怎麼寫才會在對的時候被叫出來、停止條件和試跑怎麼寫進步驟,以及一份正本怎麼同時給 Claude Code 和 Codex 用。附我自己兩個 skill 的寫法。
Kelvin Wang · · 11 分鐘閱讀
重點整理
- 反覆交代、有好幾步、只有某些任務才需要的做法,才寫成 skill;每次都要知道的規則留在 AGENTS.md。
- description 寫做什麼、使用者會怎麼說、不用在哪裡,最重要的用途放第一句。
- 預設只讀;會改東西的步驟寫明先問人,前面放一個 lint 或 --dry-run,完成標準寫成可以檢查的資料。
- 正本放在一個 git repo,用 symlink 連到 ~/.claude/skills 和 ~/.agents/skills,定期跑檢查抓分岔。
一個 skill 就是一個資料夾,裡面一份 SKILL.md:開頭的 description 決定 AI 什麼時候把它叫出來,下面寫步驟、什麼時候停、哪一步要先問人。我自己寫 skill 的順序固定:先確認這件事值得寫,再寫 description,接著把只讀的步驟和會改東西的步驟分開,會改東西的那一步前面放一個試跑,最後找一個沒看過這個 skill 的新 agent 測。skill 去哪找、裝之前看什麼,我在〈AI 寫程式的 skill 去哪找〉寫過,這裡只講自己寫。官方文件的規格以 2026 年 11 月 17 日查詢的版本為準。
什麼樣的工作值得寫成 skill?
我的判斷是看三件事同時成立:
- 同一套做法我一直在對話裡重講。每次都要重新交代「先看這個、再查那個、這個數字代表什麼」,就該寫下來。
- 有好幾步,而且順序或判讀很重要。一句話講得完的規則放規則檔就好;要照順序查、每一步的結果要怎麼解讀,才需要 skill。
- 只有某些任務需要。工具平常只讀每個 skill 的名稱和說明,任務符合時才讀全文12。每次都要知道的事放 AGENTS.md 或 CLAUDE.md,偶爾才用的做法放 skill,比較省 context。
我的門檻很簡單:只要發現自己連續三天都在做一樣的事,就把它寫成 skill。
| 放哪裡 | 適合的內容 | 例子 |
|---|---|---|
| AGENTS.md/CLAUDE.md | 每個任務都要知道、一兩句講得完的規則 | 測試指令、push 前要先問人 |
| skill | 偶爾才用、有順序和判讀的多步驟做法 | 發文草稿流程、排程健康檢查 |
| script、測試、hook | 一定要照做、可以用程式判斷對錯的規則 | 字數上限、不能出現來源沒有的數字 |
我手上兩個 skill 剛好落在這個範圍:
kw-studio-new-post。我要把一段想法變成 Threads 和 X 的草稿時用。每次都要產出同樣四個檔案(我的原話、給我看的備註、X 串文、Threads 串文),兩個平台的字數算法不一樣,最後送進我網站的後台當草稿。qn-monitor-cron。一個量化交易專案裡,有一個定時同步帳本的排程,「排程有沒有正常跑」這個問題我問過很多次。每次都要從同幾個地方、照同樣順序查,而且有幾個數字很容易看錯意思。
SKILL.md 的基本結構是什麼?
最小的 skill 只要 frontmatter 加一段說明。Claude Code 的 skill 遵循 Agent Skills 開放標準13,Codex 要求 name 和 description 兩個欄位2,所以兩個都寫,兩邊都能用:
---
name: deploy-check
description: 部署後檢查線上服務是否正常:版本、健康檢查、錯誤率。使用者說「部署完了」「上線後看一下」時使用。不用於部署本身。
---
# deploy-check
只讀。照順序做,任何一步失敗就停下來回報,不要自己修。
1. ……
2. ……
個人和專案 skill 各放在哪個資料夾、怎麼直接叫出來,skill 去哪找那篇有對照表。寫的時候要注意的差異是這些:
| 項目 | Claude Code | Codex |
|---|---|---|
| 必填欄位 | 都是選填,建議寫 description | name、description |
| 不讓 AI 自己叫 | disable-model-invocation: true | agents/openai.yaml 設 allow_implicit_invocation: false |
| 說明的長度 | description 加 when_to_use 在清單裡超過 1,536 字元會被截斷 | 所有 skill 的清單預設佔 context 的 2% |
| 本文長度 | 建議 SKILL.md 500 行以內,細節拆到旁邊的檔案 | 每個 skill 只做一件事 |
| symlink | 可以 | 會跟著 symlink 讀到實際的資料夾 |
description 怎麼寫,AI 才會在對的時候叫它?
description 是整個 skill 最重要的一段。兩個工具都先拿任務比對 description,對上了才讀全文12;description 寫不好,下面寫得再仔細也不會被讀到。
我的 description 固定寫三件事:
- 第一句寫它做什麼。兩邊的文件都建議把最重要的用途放最前面12,Claude Code 的清單裡,description 加
when_to_use超過 1,536 字元的部分會被截掉。 - 列出使用者真的會說的話。
kw-studio-new-post列的是我平常講的「寫成串文」「發文草稿」「改草稿」;qn-monitor-cron列的是「cron 有沒有跑」「對帳狀態」「監控排程正常嗎」,再加一個不是人說的觸發:告警響了的時候。 - 寫不用在哪裡。
kw-studio-new-post最後一句明確排除 PR 和 commit 訊息、規格文件、README、審查報告、公司內部文件。這一句是 2026 年 9 月 28 日審查時加的。第一版的說明寫「只要寫給人看的文字都用」,連研究整理、週報都算進去,任何要產出文字的任務都可能把它叫出來;改版後只留「我自己頻道上要公開的內容」,再把容易混淆的列出來排除。
skill 本文裡我也會再補一句「不確定該不該用時,問一句」。description 管 AI 會不會想到它,本文裡這句管邊界模糊的情況。
會改動外部東西、而且你只想自己決定什麼時候跑的 skill(部署、發布),乾脆關掉自動呼叫:Claude Code 用 disable-model-invocation: true1,Codex 在 agents/openai.yaml 把 allow_implicit_invocation 設成 false2。
停止條件和「先問人」要怎麼寫進步驟?
skill 寫的是怎麼做,但對 AI 來說,什麼時候不要做一樣重要。qn-monitor-cron 是我寫得最完整的一個,結構可以直接套用:
- 開頭一行寫權限:「只讀,自動執行。先查資料庫,必要時才連到機器上。」AI 一讀就知道這個 skill 預設不改任何東西。
- 查詢照成本排序。第一步查不需要額外登入的資料庫心跳表;第二步在同一個資料庫查對帳狀態;第三步才連到跑排程的機器看系統日誌,因為那需要另外登入,登入過期時就停下來請我登入,不自己想辦法繞過。
- 每一步附判讀。哪個數字是正常的、哪個看起來像出事其實不是。例如「最後一筆成交時間」落後好幾個小時是常態,它代表市場安靜,不代表排程死了;判斷排程活著只看心跳。
- 只能問人的那一步寫清楚。有些結論資料查不出來,例如某個部位是不是有人手動平倉。skill 裡寫:前兩步自己查,第三步只能問操作者,沒問到之前不登記、不下結論。
- 唯一的寫操作單獨一節,標明先問。補跑缺漏的資料是這個 skill 裡唯一會改東西的動作,那一節的標題就寫「唯一的寫操作,先問使用者」,並寫明跑完要清掉暫時的設定。
- 完成標準寫成資料。補跑之後不是看到綠燈就算完成,而是重查對帳、缺的那筆資料要能點名找到、數量對得上。
- 最後一節「禁止」。列出不能做的事,例如不准為了讓警示消失而調寬門檻。
kw-studio-new-post 的停止條件寫在失敗處理表:伺服器回 5xx 就告訴我,不要一直重試;其他錯誤顯示出來,最多重試一次。沒有寫停止條件的 skill,AI 遇到錯誤時最常見的反應就是換個方法繼續試。
怎麼先驗證再執行?
會送出、寫入或發布東西的 skill,我一定讓它在真的執行之前有一步可以檢查。kw-studio-new-post 的工具有三層:
lint:檢查每則貼文的長度,以及放連結的那則是不是只有短標籤加網址。X 每則 280,用加權算法(中文、全形標點和 emoji 算 2,網址算 23);Threads 每則 500 字元。不合格的會指出是第幾則。submit --dry-run:把要送出的內容印出來,不送。submit:送出前再檢查一次長度,另外拒絕貼文裡出現我的原話和備註都沒有的數字。
SKILL.md 寫明順序:先改寫、跑 lint、照它指出的地方改、再 lint,然後才 submit。就算全部通過,送出去的也只是草稿,資料庫只讓 AI 送的內容停在「AI 草稿」狀態,發布要我在後台點頭。
我寫 skill 時一直守著一條原則:文字規則擋不住的,就改寫成程式檢查。「不要寫來源沒給的數字」原本只是 SKILL.md 裡的一句話,測試後我把它改成 submit 會直接拒絕。Codex 的文件也是同樣的分法:一般用文字指示,需要確定結果或要用外部工具時才寫 script2。
自己的 skill 要套這個做法,不一定要寫一整支工具:
- 有 script 的,加一個
--dry-run或lint子指令,SKILL.md 規定先跑它。 - 只是一串指令的,在步驟裡先列「會執行的指令」給你看,你回覆後才執行。
- 改檔案的,先產生 diff,看過再套用。
寫完怎麼測試一個 skill?
Claude Code 的文件建議做對照:在全新的對話裡,用實際會遇到的要求,分別跑有 skill 和沒有 skill 的版本,比較它有沒有在對的時候被叫出來、結果對不對;對照組可以用 skillOverrides 把那個 skill 關掉1。Codex 的文件則建議拿幾個測試用的提問去對 description,確認觸發行為正確2。
我的做法跟這個一致,多兩個習慣:
- 用新的 agent 測。寫 skill 的那個對話已經知道所有背景,測不出 SKILL.md 漏寫了什麼。
kw-studio-new-post每次大改,我都讓一個全新的 agent 從頭照著做一遍,一路跑到submit --dry-run通過。 - 加一句會把它往錯的方向推的要求。例如「寫得有說服力一點」,看規則在壓力下撐不撐得住。撐不住的那一條,就照前一節的原則改成程式檢查,而不是再多寫一段說明。
skill 的正本要放哪?
我的規則是每個 skill 只有一份正本,放在 git repo 裡,其他位置都是 symlink:
- 個人 skill:
~/ai-config/skills/<名稱>/,目前 15 個。 - 專案 skill:正本留在那個專案的 repo,在
~/ai-config/skills.manifest登記一行:名稱、GitHub repo、repo 裡的路徑。只給自己用、不發給同事的,最後加optional,沒 clone 那個 repo 時就略過。
我堅持這件事是有原因的:2026 年 10 月 12 日我整理技能時,發現有六個專案 skill 只存在 ~/.claude/skills 底下,是實體資料夾,沒有版本控制也沒有備份。那天把它們搬進專案 repo 當正本,原本的位置改成 symlink。qn-monitor-cron 就是其中一個。
還有一點要注意:專案 skill 在 Claude Code 讀 .claude/skills/,在 Codex 讀 .agents/skills/12。同一個 repo 兩個資料夾各放一份實體檔,久了內容一定會分岔。只放一份,另一邊用 symlink 或交給下面的腳本連。
一份 skill 怎麼同時給 Claude Code 和 Codex 用?
~/ai-config/setup.sh 做三件事:
- 把
skills/和vendor/裡的每個 skill 用 symlink 連到~/.claude/skills(Claude Code)和~/.agents/skills(Codex)。 - 讀
skills.manifest,把列在其他 repo 的專案 skill 也連到這兩個位置。 - 只在一邊有的 skill(例如某個安裝程式只裝到其中一個工具),鏡像連到另一邊,實體還是只有一份。
已經存在、不是 symlink 的同名資料夾,腳本不覆蓋,只報 CONFLICT,讓我確認後自己搬走。
setup.sh --check 只檢查不動手。裝完或移除任何 skill 之後跑一次,回報 ok 才算完成:
| 回報 | 意思 |
|---|---|
UNLINKED | 正本存在,但還沒連到其中一個工具 |
MISSING | manifest 裡的 repo 還沒 clone |
ONLY-CLAUDE/ONLY-CODEX | 只有一個工具看得到這個 skill |
DIVERGED | 兩邊同名,但指向兩份內容不同的實體 |
DUP-CODEX | Codex 安裝器的目錄又多了一份,Codex 會看到兩個 |
DANGLING | symlink 指向的資料夾已經不在 |
DUP-CODEX 這一項是因為 Codex 遇到同名 skill 不會合併,兩個都可能出現在選單裡2。Claude Code 則是個人 skill 優先於專案 skill1。兩種行為都代表同名副本會造成混亂,最省事的是根本不讓它出現。
不需要這麼完整的話,一個 git 管理的資料夾加兩條 symlink 就夠,指令在skill 去哪找那篇的「我怎麼管理自己的 skill?」。
想深入 Harness Engineering 是什麼?AI Harness 讓 AI agent 穩定做事的 7 個部分(2026) skill 只是其中一塊:規則、測試、MCP、記憶、子代理和驗收怎麼搭在一起。可以直接複製的 SKILL.md 範本
把下面這份存成 ~/my-skills/<名稱>/SKILL.md,照你的流程填:
---
name: <名稱>
description: <一句話:做什麼>。使用者說「<原話一>」「<原話二>」時使用。不用於 <容易混淆的任務>。
---
# <名稱>
只讀,自動執行。不確定該不該用時,先問一句。
## 先讀
- <這件事已知問題和現況的文件>
## 步驟(只讀)
1. <最便宜、不需要額外登入的查詢>
- 判讀:<什麼是正常的、什麼看起來像出事其實不是>
2. <第二層查詢>
3. <需要登入或連到機器的查詢;登入過期就停下來請使用者處理>
## 只能問人的事
- <資料查不出來的結論>。沒問到之前不下結論。
## 唯一的寫操作(先問使用者)
- 先跑 <lint/--dry-run/列出指令>,給使用者看。
- 使用者同意後才執行;跑完清掉暫時的設定。
## 完成標準
- <可以檢查的資料,不是「看起來正常」>
## 失敗時
- <錯誤訊息> → <怎麼做>;其他錯誤顯示出來,最多重試一次。
## 禁止
- <不能做的事>
常見問題
skill 和 AGENTS.md 裡的規則差在哪?
AGENTS.md、CLAUDE.md 每次對話都整份載入;skill 平常只載入名稱和說明,任務符合時才讀全文12。每個任務都要遵守的寫在規則檔,某類任務才用的做法寫成 skill。
skill 可以附 script 嗎?
可以。Claude Code 建議把詳細資料和 script 放在 skill 資料夾裡,從 SKILL.md 指過去,需要時才讀或執行1;Codex 的 skill 可以有 scripts/、references/、assets/ 資料夾2。需要確定結果的檢查(字數、格式)寫成 script,判斷和順序寫在 SKILL.md。
為什麼 AI 沒有自動叫我的 skill?
先檢查 description:是不是沒寫使用者實際會說的話,或者最重要的用途沒放在第一句。再確認工具真的看得到它:Claude Code 直接打 /名稱,Codex 打 $名稱 或 /skills,叫不出來就是位置或 symlink 有問題。Codex 通常會自動偵測變更,沒出現時重開2。
資料來源