Always in the middle of something.

TL;DR: Your first Claude Code skill won’t look like the polished examples you’ve read about. It’ll look like a prompt you’ve typed three times in a row, saved into a .md file. This post walks through that minimum-viable shape with a hypothetical four-line /structure-findings skill, shows the three things that break when you save it and type the slash command, then compares it to a real seventeen-line production-grade skill from the framework I use day to day. The longer one has more lines because it has older scars. That’s the whole arc. ...

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, 三個列點。」打過三次, 想存。 ...

TL;DR: A skill I asked Claude to draft came back as thirteen lines of markdown. Less than a function. The thirteen lines aren’t the skill — they’re a dispatcher pointing to a longer file where the contract actually lives. That split is what separates a skill from a prompt. And the part the model was reliably wrong about — the real interface of the external tool the skill talks to — is the part a human still has to verify. ...

TL;DR: 我請 AI 幫我寫一個能從 Claude Code 裡呼叫 OpenAI Codex CLI 的 skill,它給我 13 行 markdown。看起來小到不像個東西。但這 13 行不是 skill 的全部——真正讓它變成 skill 而不是 prompt 的,是它指過去的那一份比較厚的東西。Skill 是契約的形狀,不是指令的形狀。 前三篇我談過 skill 是什麼。一個 AI Skill 和 Prompt 到底差在哪 把它放進 stack 裡的某一層, Skill 邊界設計 講為什麼邊界比能力重要, Skill Design as Interface Design 是英文版用 API 設計的角度寫的。 這篇換個角度:真的拿一個給你看。 挑 /codex-cli 這個 skill,因為它小到適合當教材。它在我那邊的工作是:從 Claude Code 想把某個任務丟給 OpenAI 的 codex CLI 去跑,我打 /codex-cli 修 README 的 typo,它就接手。 13 行長這樣 我請 AI 幫我寫第一版的時候,它給我這個: # /codex-cli Execute the canonical workflow: `.agent/workflows/codex-cli.md` ## Execution Follow every step in `.agent/workflows/codex-cli.md` sequentially. The user's task description is: $ARGUMENTS - [OPTIONAL MODULE] Requires globally installed `codex` CLI (`npm install -g @openai/codex`). - If CLI is unavailable, inform the user and fall back to native execution. - End response with ⚡ ACX. 就這樣。13 行。沒有複雜的 prompt engineering, 沒有冗長的 system message, 沒有 chain-of-thought 模板。第一次看到的時候我有點疑惑:這就是一個 skill? ...

TL;DR： MCP 在一年多內，從 Anthropic 的內部實驗變成 AI 業界共通的介面。但進入 2026 年，資安研究員一個接一個把它拆開：官方 SDK 的 by-design RCE、tool poisoning、rug pull。我的看法是，這些漏洞大多不是協定的 bug，而是「把能力交出去、卻沒把治理一起交出去」的必然結果。現在大家急著補的那些東西，OAuth scope、人工確認、伺服器註冊表，其實就是治理被重新貼回協定上。 2026 年 4 月，資安團隊 OX Security 公布了一個發現：MCP 的官方 SDK（Python、TypeScript、Java、Rust 全中）存在一條從設定檔直接到指令執行的路徑，攻擊者可以在任何跑著有問題實作的機器上執行任意系統指令。根據他們的估算，受影響的套件下載量超過 1.5 億次，潛在波及的伺服器實例上看 20 萬個（The Register 的報導用的標題就是「20 萬台伺服器有風險」）。後續整個生態跟著冒出一連串 CVE，包括 MCP Inspector 的 CVE-2025-49596 和 Cursor 的 CVE-2025-54136。 但真正讓我停下來想的，是 Anthropic 的回應：這是設計如此（by design）。他們不打算改協定，並表示輸入清洗是開發者自己的責任。 這句話可以有兩種讀法，而我認為兩種都對。這正是整件事最值得想的地方。 先講清楚：MCP 為什麼會贏 要評論 MCP 的資安問題，得先承認它解決了一個真的很煩的問題。 在 MCP 之前，每接一個工具到 AI 上，你就得寫一套各自為政的膠水。M 個模型乘上 N 個工具，等於 M×N 種接法。MCP 把它變成 M+N：工具實作一次 server，模型實作一次 client，中間用同一套協定講話。Anthropic 當初的比喻是「AI 的 USB-C」，這個比喻站得住，是因為它真的描述了發生的事。 ...

TL;DR: MCP went from an Anthropic side-project to the industry’s default agent-to-tool interface in about a year. Then 2026 brought a steady drip of disclosures: a by-design RCE in the official SDKs, tool poisoning, rug pulls. My read is that almost none of these are protocol bugs. They’re what happens when you ship capability without shipping governance, and the patches now landing (OAuth scopes, human-in-the-loop, registries) are just governance being bolted back on. ...

TL;DR: 一個 skill 會多可預測,大概就看它的邊界劃得多清楚。把它當成「能力」(這個 skill 讓 AI 會做 X),它容易亂跑;把它當成「合約」(講好輸入、輸出、以及它不會碰什麼),它就比較像一個設計良好的 API。重點不是寫更多「要小心」,而是把它能碰的範圍框住。 我有個 skill,前一天還用得好好的,隔天就開始亂搞:我要它做 A,它順手把旁邊的 B 也「幫我」改了。我第一個反應是怪模型今天狀況不好。後來才想通,問題在我自己——當初寫這個 skill 的時候,我只說了它「會做什麼」,沒說它「不能碰什麼」。 這是英文版的中文對照,英文那篇用 API 設計的角度談;這篇是我自己怎麼從「能力」這個想法,慢慢搬到「合約」這個想法的過程。 能力清單 vs 合約 我們很習慣用「能力」來描述一個 skill:「這個 skill 讓 AI 會跑測試」「這個會幫我部署」。這種講法很自然,也很容易讓你之後被嚇到。因為「會跑測試」這句話沒有邊。它沒講會讀什麼、會動什麼、遇到不在預期內的狀況時會怎麼處理。 合約天生就有邊。它講清楚什麼東西進去、什麼東西出來、以及哪些地方它不會碰。框架文件裡有一句講得比我直接:skill 應該被當成「有版本、受政策約束、能力被框住的封裝」,而不是「一堆鬆散的 prompt 檔」。這跟一個 AI Skill 和 Prompt 到底差在哪講的是同一件事:重點不是 AI「能」做那件事,而是那件事被「講清楚」了。 合約先行:先想清楚它不該做什麼 我看過一個還算貼切的比喻:skill 像是你交給一位很強的廚師的食譜。食譜提供的是結構:材料、順序、限制;廚師提供的是判斷,什麼時候醬汁該再收一下、什麼時候可以換個材料。你不會因為廚師很強,就把食譜寫成「做一道好吃的菜」。 skill 也一樣。模型本身的判斷力很好,所以你要補的不是判斷,是結構。而結構裡最常被漏掉的,就是那條「不要碰」的線。我現在寫一個 skill,會先問自己一個問題:這個 skill 最不該做的事是什麼? 把那條線寫進去,比再多寫三條「請謹慎處理」都有效。 邊界鬆掉,其實是一次沒講的破壞性變更 框架裡有一個原則我覺得很受用:寧可在邊界上把關,也不要去微管模型怎麼想。一個會亂跑的 skill,你通常修不好它的「想法」;你能做的是把它能碰的範圍(哪些檔案、哪些工具、多少預算)框起來。 一個 skill 的範圍如果隨著時間悄悄變大,那其實是你發佈了一次「破壞性變更」卻沒有改版本號。而呼叫它的人(就是你自己)會用最經典的方式發現這件事:在出事的時候。這也是AI 代理常見痛點裡那個「能力邊界」缺口最貴的一種表現形式。範圍,只是它最容易爆出來的地方。 我把一個 skill 從能力改成合約的前後 回到開頭那個亂改 B 的 skill。它原本的描述大概是「整理這個模組的程式碼」。很開放,聽起來很厲害,結果就是它對「整理」的理解跟我不一樣。 我後來把它改寫成比較像合約的樣子:輸入是「指定的那幾個檔案」,輸出是「格式化後的同一批檔案 + 一份它改了什麼的清單」,然後明確寫上「不要新增或刪除檔案、不要碰指定範圍以外的東西」。改完之後它沒有變笨,只是不再自作主張。差別不在能力,在邊界。 順帶一提,邊界清楚的 skill 通常也比較便宜。skill 是漸進載入的:AI 先讀那一小段 metadata 判斷現在用不用得上,真的要用才載入完整內容。一個邊界小而清楚的 skill,光看它的「合約」就能被快速略過;一個什麼都做的 skill,得把整包拖進 context 才發現其實不該用它。這跟我在 Token 成本那篇講的是同一個方向:清楚的小合約,既好預測也比較省。 ...

TL;DR: An agent skill behaves predictably to about the degree its boundary is specified. Described as a capability (“the agent can now do X”), a skill tends to drift. Described as a contract (declared inputs, declared outputs, a scope it promises not to exceed), it behaves more like a well-designed API. The interface-design habits engineers already have (stable contracts, explicit scope, versioning) seem to transfer directly. The framework’s own direction points the same way: skills as versioned, capability-bounded packages, with boundary enforcement instead of micromanaging how the model reasons. ...

TL;DR: 把 token 當成設計變數,不是月底才看的帳單。沒有治理的任務成本沒有上限;但反過來,把任務切得愈細也不會愈省——subagent 不共享快取、TTL 一過就重建,過度切分反而更貴。真正要找的是「對的顆粒度」:夠細到 AI 不會亂跑,夠粗到能一直讀同一份熱快取。這些數字會隨工具一直變,當概念看就好。 有一陣子我根本不看 token 花多少。直到某次一個自動重構的任務跑了大半個晚上,我隔天看用量才意識到一件事:這東西的成本不是「用完才知道」,是我在開始之前就決定好的。 這篇是英文版的中文對照,但角度不太一樣。英文那篇用比較分析的方式談「為什麼治理的成本是可預測的」;這篇是我自己一路試出來的版本,包括一個我原本以為對、後來發現錯的直覺。 Token 成本是開始任務前就決定的 一個任務會花多少 token,大部分在它「被分類」的那一刻就定了:要載入多少 context、要不要去翻所有技能文件、要不要再開 subagent。等你看到數字,數字早就花掉了。 所以「之後再來省 token」通常沒什麼用。貴的決定都在前面:把整個 codebase 讀一遍而不是先看索引、載入完整的技能定義而不是它的 metadata、把一個本來可以接續的工作當成全新的冷啟動重跑一次。這些事後很難補救,你能做的是下次分類分得好一點。 只用 Prompt 和技能,也能做到基本治理裡我提過,最便宜的那層治理,一個 CLAUDE.md 加一句「commit SHA 是什麼」,幾乎不花錢,原因就在這裡:它把決定提前到任務開始之前。 粗放的成本沒有上限 我後來想通的一件事是,token 成本其實分成兩種,差別不在多寡,在有沒有天花板。 有治理的工作有上限。Agentic OS 的 benchmark 裡最重的情境,一個跨多代理協作的架構變更,大約落在 6 萬 token 上下。你可以嫌它高,但很難說它「沒有上限」:它是個數字,事前就知道,而且你不看它的時候它不會自己長大。 放著不管的工作沒有這個上限。當 AI 說「好了」而你手上沒有任何可以查的東西,真正貴的不是它說那句話的 token,是後面所有建立在這個假完成上的工作。這個系列的第一篇有個具體例子:AI 說它實作了三個模組,其中兩個根本沒動過。它報告完成花的 token 很少,失控的是下游每一步都信了這份假報告。少了 evidence 的失敗反而是便宜的那種,你很快會發現;貴的是那種安靜地累積、等你發現已經繞很遠的。 治理在這個角度下,其實不是為了少花 token。它比較像是把花費從「沒上限」那一欄,搬到「有上限」那一欄。 我原本以為切細一點就省,結果不是 想通上面那點之後,我自然得出一個結論:既然結構能把成本框住,那就把任務切到最細吧。這個直覺在遇到快取之後就破了。 快取的算式大概是這樣(2026 上半的數字,而且它一直在動):讀快取大約是正常 input token 的十分之一,寫快取反而比正常還貴,短窗約 1.25 倍、長窗約 2 倍。也就是說,折扣只有在你「重複讀同一份快取」時才出現;每寫一份新的,你都在付溢價。 這就把「愈小愈省」整個翻過來,因為切分和快取有兩個很不友善的互動: subagent 預設不繼承父代理的快取。 每開一個新的子任務,它通常要為自己需要的前綴重新付一次寫入。一個任務切五份,你可能是買了五次寫入,而不是把一次寫入攤平成很多次便宜的讀取。(現在有些工具開始提供 fork 模式讓子代理重用父快取——這件事本身就說明這個成本真實到值得工程繞過。) 快取有 TTL。 預設窗口很短。如果你把工作切到步驟之間的間隔超過它(某個 subagent 跑太久才回來、某個 fan-out 卡住),快取就過期了,下一步只能用全價重建。 所以一個切太細的任務,最後可能比它取代的那個粗版本更貴:更多寫入、更少讀取、更多重建。同一份 benchmark 也驗證了反方向:一個「載入一次、之後都從快取讀」的接續模型,比每次都整份重讀省了大約一半的執行成本。真正在省的是快取的連續性,不是任務切得多細。 ...

TL;DR: Governance tends to have a token cost you can put a ceiling on. Ungoverned work usually doesn’t; the recovery cost of an undetected error has no obvious upper bound. But the fix isn’t “split everything into the smallest possible pieces.” Caching changes the math: a fresh sub-context pays a cache-write premium and doesn’t inherit its parent’s cached prefix, so over-decomposition can cost more than the coarse version it replaced. The design target, at least with today’s caching, is the granularity that holds error cost and cache cost in check at the same time. It’s a moving target (pricing and model behavior change fast), so treat it as a way of thinking, not a fixed rule. ...