想聽原音逐字版？這支影片是整套框架的出處；下方重點摘要可以直接當導覽用。
00:00:52 Skill hell 定義——一堆免費技能，你分不出好壞，也拿不到它們號稱的成果。00:02:12 檢查清單登場——Trigger、Structure、Steering、Pruning 四關卡。00:03:37 ① Trigger——user-invoked vs model-invoked；context load 燒 token，cognitive load 壓在你身上。00:06:07 Matt 為什麼偏好 user-invoked——移除一整類「技能有沒有被正確觸發」的問題。00:07:30 ② Structure——steps + reference 兩大單元，SKILL.md 越小越好。00:10:51 context pointer——把分支用的參考藏到主檔外，需要時才拉。00:11:54 ③ Steering——leading words（引導詞）讓 agent 自己複述你的詞。00:13:00 vertical slice 範例——用一個詞取代「不要一層一層寫」的整段懇求。00:14:55 legwork——把後續步驟藏起來，逼 agent 把當下這一步做深。00:16:50 ④ Pruning——DRY / single source of truth、sediment、no-ops。00:18:38 deletion test——刪掉一段，行為沒變，那段就是該死。This guide distills Matt Pocock's talk "Building Great Agent Skills: The Missing Manual" (AI Engineer World's Fair) into a four-gate checklist you can run against any skill you write — or any skill you download. The same checklist is encoded, machine-readable, in the writing-for-agents skill.
這份指南把 Matt Pocock 在 AI Engineer World's Fair 的演講 「Building Great Agent Skills: The Missing Manual」 濃縮成一份四關卡檢查清單，你可以拿它來檢視自己寫的任何技能——或任何下載回來的技能。同一套檢查清單，也被編碼成機器可讀的 writing-for-agents 技能。
We developers seem to be pretty talented at finding different forms of hell for ourselves. A few years ago we had tutorial hell — go into a bunch of tutorials, never piece it together. Then framework hell — a new JavaScript framework announced every ten minutes. And now we have another one: skill hell.
我們開發者似乎很擅長替自己找各種地獄。幾年前有 tutorial hell（教學地獄）——進了一堆教學，卻永遠拼不起來。然後是 framework hell（框架地獄）——每十分鐘就有個新的 JavaScript 框架問世。現在又多了一個：skill hell（技能地獄）。
Skill hell is where you have all these skills freely available — download them, contribute to them, figure them out on your own — but you can't tell a good skill from a bad one. You can't see how the pieces all work together, and you don't get the results the skills themselves promise. Bad skills are worse than no skills: they burn your tokens, steal the agent's attention, and steal your trust.
Skill hell 是當你有滿坑滿谷可以免費下載、可以貢獻、可以自己摸索的技能，但你分不出好技能跟壞技能，看不出這些零件怎麼拼在一起，最後拿不到技能「號稱」能給你的成果。壞技能比沒技能更糟：它們燒你的 token、偷走 agent 的注意力，也偷走你對它的信任。
What's missing is a shared rubric: a way to look at a skill and say "these are the good things, these are the bad things." Here it is. Four gates, in order: Trigger (how the skill gets invoked), Structure (how the skill is composed), Steering (how you get the agent to do what you want), Pruning (how you make the skill as small as possible).
缺的是一份共享的評分表：一個能讓你看著技能說「這些是好的、這些是壞的」的框架。就是它。四道關卡，依序是：Trigger（觸發）——技能怎麼被叫起來；Structure（結構）——技能內部怎麼組成；Steering（引導）——你怎麼讓 agent 做你要它做的事；Pruning（精簡）——你怎麼把技能做到盡可能小。
A skill can be invoked two ways. Model-invoked skills carry a description that sits in the agent's context window; the agent reads it and decides to pull the SKILL.md in. That description is a context pointer. User-invoked skills hide the pointer — the description only shows to the user (disable-model-invocation: true), so the agent can't trigger them on its own.
技能有兩種叫法。Model-invoked（模型觸發） 的技能帶有一段 description，常駐在 agent 的 context window 裡；agent 讀到後決定要不要把 SKILL.md 拉進來。那段 description 就是一個 context pointer（脈絡指標）。User-invoked（使用者觸發） 的技能把指標藏起來——description 只給使用者看（disable-model-invocation: true），所以 agent 自己觸發不了。
Model-invoked sounds strictly better — more flexible, the model can grab it when appropriate. But every model-invoked skill adds context load: another description costing tokens on every single request, plus another thing for the agent to think about. A hundred model-invoked skills is a hundred descriptions sitting in context.
Model-invoked 聽起來全面比較好——更靈活，model 可以在適合的時候自己伸手。但每多一個 model-invoked 技能，就多一份 context load（脈絡負擔）：每一次 request 都要多燒一份 description 的 token，也多一件讓 agent 分心的事。一百個 model-invoked 技能就是一百段 description 塞在 context 裡。
User-invoked skills push the cost the other way — cognitive load on you. The more user-invoked skills you have, the more you have to keep in your head about which to call when.
User-invoked 技能把成本推到另一邊——壓在你身上的 cognitive load（認知負擔）。User-invoked 技能越多，你得記在腦子裡「什麼時候該叫哪個」的就越多。
The two philosophies map onto real skill sets: Superpowers is primarily model-invoked (give the agent superpowers); Matt prefers being in full control — user-invoked keeps the agent's context load small and removes an entire class of problem: "is my skill being called at the right time?" There's no free lunch — pick based on whether you want control or flexibility.
兩種哲學各自對應到真實的技能集：Superpowers 以 model-invoked 為主（把超能力交給 agent）；Matt 偏好自己掌握方向盤——user-invoked 讓 agent 的 context load 保持最小，也直接消掉一整類問題：「我的技能有沒有在對的時機被觸發？」沒有免費的午餐——看你要掌控還是要彈性，二選一。
A skill is composed of two main units. Steps are the step-by-step procedure the skill walks through. Reference is any supporting information that helps it walk through those steps. Skills can be all steps, all reference, or both — thinking of them this way makes them much easier to break down and write from scratch.
一個技能由兩大單元組成。Steps（步驟） 是技能會一步步走完的程序。Reference（參考資料） 是幫助它走完那些步驟的輔助資訊。技能可以全是步驟、全是參考、或兩者皆有——用這個角度想，技能就好拆解、也容易從零寫起。
Then the hard constraint: make the main SKILL.md file as small as possible. Smaller skills are easier to maintain, easier to audit, and every word you shave is a token shaved from your skills cost, on every request.
然後是硬性限制：讓主要的 SKILL.md 檔案盡可能小。 技能越小越好維護、越好稽核，而且你每砍掉一個字，就是在每次 request 的技能成本上省下一個 token。
The technique for keeping it small is progressive disclosure: think about the branches of the skill — the different ways it can be used. Reference material that only matters for one branch is a candidate for removal from the main file. Point the main file at it with a context pointer — an external reference file bundled alongside the skill that the agent pulls in only when it needs that branch.
讓它保持小的技術叫 progressive disclosure（漸進式揭露）：想想技能的 branches（分支）——技能各種不同的用法。只有某個分支用得到的參考資料，就是移出主檔的候選。用 context pointer（脈絡指標） 指向它——一個跟技能捆在一起的外部參考檔，agent 只在需要那個分支時才拉進來。
This is the highest-leverage gate. Agents often don't do what you want because you're not using leading words — compact concepts already in the model's pre-training that pack a lot of meaning into a small space. Put the leading word in the skill text; the agent repeats it back to itself in its reasoning, and because it keeps re-emphasizing that word, its behavior follows.
這是槓桿最高的一道關卡。Agent 常不照做，是因為你沒用 leading words（引導詞）——那些早就活在模型預訓練裡的緊湊概念，把小空間塞進大量意義。把引導詞放進技能文字，agent 在推理時會一直把它複述給自己聽，而正因為它不斷強調那個詞，它的行為就跟著走了。
Classic example: agents code layer by layer — all the database, then all the schemas, then all the API, then the front end. You could write a paragraph begging them to build something small and working first. Or you put in the leading word "vertical slice" — a well-known development term that triggers the agent's priors. You can even verify it worked: watch the reasoning traces, and you'll see the agent muttering "we'll do this as a thin vertical slice."
經典案例：agent 習慣 一層一層 寫程式——先整個資料庫、再全部 schema、再全部 API、最後才前端。你可以寫一大段懇求它先做出小東西、先能跑再說。或者你丟進引導詞 「vertical slice（垂直切片）」——一個開發圈耳熟能詳的詞，會觸發 agent 的先驗。你甚至能驗證它有沒有生效：看 reasoning traces，就會看到 agent 自言自語「我們先做一個薄的垂直切片」。
The second lever is legwork — the agent skimps on a step when it can see the finish line. The classic case is plan mode: "ask clarifying questions" never gets enough effort because the agent sees the ultimate goal (create a plan) and rushes toward it. Matt's solution: split the planning into its own skill so the agent only sees one step at a time. Hiding the future goal forces focus on the current step. Sometimes giving less information is what makes the work deeper.
第二根槓桿是 legwork（實地功夫）——當 agent 看得到終點線時，就會在某個步驟上偷懶。經典案例是 plan mode：「問澄清問題」永遠得不到足夠的功夫，因為 agent 看得到最終目標（產出計畫），就急著衝過去。Matt 的解法：把規劃拆成獨立的一個技能，讓 agent 一次只看得到一步。把未來的目標藏起來，反而逼出對當下這一步的專注。有時候「資訊給更少」才是把工作做深的方法。
A massive skill is usually a symptom of another failure mode. Run three checks:
一個巨大的技能通常是別的失敗模式的症狀。跑三項檢查：
Don't repeat yourself. Every part should have a single source of truth — one authoritative place, so changing behavior is one edit in one place. Watch for duplication across reference material too.
不要重複自己。 每一塊都該有 single source of truth（單一真實來源）——一個權威位置，讓「改變行為」就是「在一個地方改一次」。連參考資料之間的跨檔重複也要注意。
Watch for sediment. When people work on the same shared docs and nobody feels brave enough to delete or modify anyone else's, you end up with a huge pile of often-irrelevant material. If added material isn't relevant for all branches, move it into the right branches — or kill it.
留意沉積（sediment）。 當一群人一起編輯同一份共享文件、又沒人敢刪或改別人的東西時，最後就會沉積出一大坨常常跟主題無關的內容。如果加進去的東西不是所有分支都用得到，就把它移進對的分支——或直接砍掉。
Hunt no-ops. These are the classic agent-written-skill disease: things that appear to do something but don't actually influence the agent's behavior. The test is a deletion test: delete the paragraph and ask whether the agent's behavior changes. If it doesn't, that paragraph was a no-op. Delete the whole sentence, not trimmed words — and judge disagreements by running the skill, not by debating.
獵殺空指令（no-ops）。 這是 AI 寫的技能最經典的病：看起來在做事、實際上完全沒影響 agent 的行為。測試方法是 deletion test（刪除測試）：把那一段刪掉，然後問 agent 的行為有沒有變。沒變，那段就是 no-op。要刪就刪整句，不是修修剪剪——而有爭議時，用「實際跑一次」來裁決，不要用辯論。
All of this was encoded into a skill in Matt's repo — originally called writing-great-skills, renamed in v1.1 to writing-for-agents. It's the reference for writing any agent-facing document: skills, AGENTS.md/CLAUDE.md, specs, tickets. The skill-specific mechanics (frontmatter, model- vs user-invoked, router skills) live in SKILL-MECHANICS.md. Run this four-gate checklist over any skill you're about to install — or over the SOP that nobody follows.
以上全部被編碼進 Matt repo 裡的一個技能——原名 writing-great-skills，v1.1 改名為 writing-for-agents。它是撰寫任何「給 agent 看」的文件的參考：技能、AGENTS.md/CLAUDE.md、規格、ticket。技能專屬的機制（frontmatter、model- vs user-invoked、路由器技能）放在 SKILL-MECHANICS.md。把你正要安裝的任何技能——或那份沒人照做的 SOP——拿來跑一遍這四關吧。