TL;DR: 你的第一個 skill 不會長得像書裡那些 production-grade 的成熟形態, 它會長得像「你重複打三次的同一個 prompt」。本篇示範一個假設的 4 行入門版怎麼寫、存到哪裡、為什麼會沒跑、撞坑後怎麼修, 然後對照我自己框架裡真的在用的 17 行版本 — 看那些多出來的東西其實都是「撞坑後加上的補丁」, 不是設計階段一次想出來的。

你有沒有打過同一個 prompt 三次?同一段話、同一個格式、同一個角度, 三次。第三次你會開始煩, 第四次你會想:這個我能不能存起來?

那一刻其實就是你的第一個 skill。

不是說那個 prompt 寫得有多好, 是「想存起來」這個衝動就是 skill 出現的位置 — 你已經辨識出一個重複會發生的模式。剩下的事沒什麼神秘的, 把它丟進一個 .md 檔, 用 slash 叫出來而已。

前三篇我談過 skill 是什麼 ——跟 prompt 的差別在哪一層、邊界怎麼劃、拆一個 13 行的 dispatcher 給你看。但這篇有個之前都沒講的事:你的第一個 skill 不會長得像那些。你看過的成熟 skill, 不管是我框架裡的還是別人的, 都是寫了很多次、撞了幾次坑之後才變成那樣的。直接從那邊倒著學, 容易卡在「為什麼要有這條」這種對學習沒幫助的地方。比較好的起點, 就是你那個煩躁的 prompt。

假設你常做研究

舉個例子。你最近常請 AI 幫你看一些雜七雜八的研究筆記 — 三段你 google 來的東西、半段別人 Slack 給你的、一張 issue 截圖貼的內文。你想把它分類:哪些是已經查證的事實、哪些是還沒驗證但你假設成立的、哪些是現在還不知道的問題。

每次貼進去你都打差不多的字:「幫我把下面這團分成 Facts / Assumptions / Unknowns, 三個列點。」打過三次, 想存。

我框架裡其實沒這個 skill, 但你入門版大概會長這樣:

# /structure-findings
Take the messy research notes I paste in. Split them into three groups:
Facts (verified knowns), Assumptions (believed but not checked), Unknowns (open questions).
Input: $ARGUMENTS

那 4 行做了什麼?第一行 /structure-findings 是觸發詞, 你在 Claude Code 裡打那個 slash 命令時, 它會找這個檔。中間兩行是你原本的 prompt, 不過從你打字直接送, 變成寫進檔案裡。最後一行 $ARGUMENTS 是 placeholder — 你輸入「/structure-findings 接著貼一坨筆記」的時候, 那一坨會被代進去。

老實說, 大概這樣就夠了, 一個能跑的 skill 已經在你手上。

然後它沒跑

把那 4 行存到 .claude/commands/structure-findings.md。注意是 project-local — Claude Code 從你開 session 的目錄(cwd)往下找這個資料夾, 找不到就當作這個 skill 不存在。

在 Claude Code 裡打 /structure-findings 貼上你那團研究筆記, 看它有沒有動。

如果你跟我一樣會撞坑, 大概會撞到三種:

打完沒反應。 多半是 cwd 不對。你以為的「我已經在這個專案裡了」跟 Claude Code 認的 cwd 不一定一樣 — 它從哪個目錄開的 session, 就只在那裡(以及更上層)找 .claude/commands/。檢查一下 session 開在哪。

$ARGUMENTS 是空的, 它把你的話當成不重要的尾巴。 兩個可能 — 一個是你 skill 內容裡根本沒寫到要用 $ARGUMENTS placeholder, 一個是 Claude Code 的某些版本對 placeholder 的解讀有差異。這條建議直接對著 Claude Code 官方 skills 文件 確認當前版本怎麼算。

跑了, 但結果跟你直接打 prompt 沒兩樣。 我第一次撞到這個有點傻 — 想說我都存成檔了, 怎麼還是 prompt 的感覺。後來發現差別其實在那 4 行裡有沒有「規定輸出長什麼樣」。如果你只寫「幫我分類」, 結果就會跟你直接打字一樣鬆。把「Facts / Assumptions / Unknowns 各列成一段, 標題粗體」這種輸出格式寫死進去, 它才有 skill 的樣子。要不要寫死, 你跑兩次就會知道。

順帶一提, 這三個坑我自己都踩過, 第三個還踩了兩次才認帳。

同樣的事, 在我框架裡

我自己日常在用的框架 AgentCortex 裡, 有一個 skill 叫 /research。它做的事比剛剛那個假設的 /structure-findings 大 — 但你打開那份 workflow, 會發現裡面有一個步驟長得跟你剛剛寫的東西幾乎一模一樣。

/research 的 workflow 規定 AI 把找到的東西用六個類別寫出來(規矩寫得比我當下需要的多一點, 後來才知道為什麼):Facts(查證過的)、Unknowns(需要再找的)、Assumptions(相信但沒驗證的)、Risks(風險, 分高中低)、Official References(查過的官方資料)、Next Actions(具體下一步)。

你看出來了嗎?你那個假設的 4 行 /structure-findings, 基本上就是 /research workflow 的其中一個 step — 把雜亂內容分成 Facts / Assumptions / Unknowns 那塊。我多加了 Risks、Refs、Next Actions 三個類別, 但骨子是同一件事。這幾個多出來的類別都是一段時間累積出來的, 不是設計階段一次想到的。

production grade 的版本長什麼樣

那 production 形態具體長什麼樣?我把真實的 /research skill 貼出來給你看 — 路徑是 .claude/commands/research.md, 17 行:

# /research

Execute the canonical workflow: `.agent/workflows/research.md`

## Required reads before execution

1. `AGENTS.md` — global directives (Intent Router, Gate Engine, Sentinel)
2. `.agentcortex/context/current_state.md` — SSoT

## Execution

Follow every step in `.agent/workflows/research.md` sequentially.
The user's task description is: $ARGUMENTS

- This is a research-only workflow. No implementation — only understanding.
- Investigate first, report after. Ground findings in evidence.
- End response with ⚡ ACX.

跟假設的 4 行版對著看, 多了什麼:

Required reads。 我規定 AI 在執行前先讀兩份檔 — 一個是專案的全局 directives, 一個是目前系統狀態的 single source of truth。為什麼?因為早期我發現 AI 如果直接接到指令, 它的答案會跟我系統現在的狀態脫節。多了這條, 它至少先把當下的 context 拉進來。

$ARGUMENTS 還在, 身邊多了配套。 「research-only, no implementation」「investigate first, report after」— 這些是行為約束。不是說 prompt 不能寫這些, 是當你把它寫進 skill 而不是每次都重打, 那條約束就變成這個 skill 的契約的一部分。

它指向另一個檔, 不在這 17 行裡。 跟上一篇 拆 /codex-cli 看到的是同一個模式 — 真正執行細節在 .agent/workflows/research.md, skill 本體只負責把任務 dispatch 出去。順帶一提這是我框架的習慣, 不是 Claude Code 自帶, 你不照這套也完全可以。

每一個多出來的東西, 都不是設計階段就想到的, 是某次撞到一個失敗模式之後加上去的。「為什麼要 required reads?」因為有一次它答得超脫離現實。「為什麼加 read-only?」因為有一次它沒被約束就動了不該動的東西。行數就是這樣一坑一坑長出來的, 不是設計成這樣的。

你的下一個轉折點

寫了幾個 atomic skill 之後, 你會開始注意一件事 — 有些 skill 老是接在一起跑。第一次你不會發現, 第三次你就會發現自己每次都這樣串。

你先 /structure-findings, 把筆記分成三類。看完那份報告, 你想接著問:這些 Assumptions 裡哪些風險最高?所以你開了第二個 skill /list-risks。看完風險, 你想決定下一步, 又呼叫第三個 /next-actions。

你發現了嗎 — 這三個 atomic 加起來, 幾乎就是我前面 /research 那六類(少了 Refs)。三個 skill 跑完才完成一次「研究」, 而且每次研究都是這三個一起跑。

那大概就是 workflow 開始浮出來的時候。你還沒想設計它, 它自己就長出來了。Workflow 不是設計階段就分好的東西, 是你重複幾次、撞到模式、自然分出來的。當你發現自己有幾個 atomic 老是同序列出現, 把它們綁成一份, 給一個總的 skill 觸發 — 那就是我 /research 跟它那份 workflow 檔的由來。

從那個煩躁的 prompt 開始

寫 skill 這件事我還在摸索, 但有一個觀察愈來愈確定:從 production-grade skill 倒著學, 比從那個煩躁的 prompt 正著走難很多。

倒著學要你猜「為什麼有這條」、「為什麼分成這幾層」、「為什麼要 dispatch」 — 都是抽象的設計題。正著走只要你做一件事:把下次想存的 prompt 真的存起來, 跑跑看, 撞到坑就修。修個幾次, 上面那些「為什麼」會自己浮出來。

我不會說我自己當初一定就是這樣開始的(實在記不清了), 但回頭看那些長到 17 行的 skill, 它們最早一定有一個 4 行的祖先, 而那個 4 行的祖先, 一定有一個更早的 — 某個我打到第三次煩躁的 prompt。

最後一句重要的話:每個工具的 skill 慣例都不一樣 ——Claude Code 官方 skills 文件、OpenAI Codex CLI docs、Cursor 的 .cursor/rules、AGENTS.md 規範, 各自有自己的形狀。寫之前對一次, 之後也記得回去對 — blog 文會過期, 官方文件不會。

Agentic OS 是開源專案:github.com/KbWen/agentic-os

延伸閱讀