3.4
Turn your way of working into skills把團隊的做法寫成 skill把团队的做法写成 skill
This chapter assumes you have read Instructions and skills: a skill is a manual that the agent reads when a job comes up.
讀這一章,請先讀過指令與 skill:只載入需要的:skill 是一本手冊,工作出現時 agent 才去讀。
读这一章,请先读过指令与 skill:只加载需要的:skill 是 agent 在某项工作出现时去读的手册。
The Knowledge經驗分享经验分享
In one sentence
A good skill says how this job is done here and where it goes wrong, not what a textbook says. When a job with several steps has been done by hand about three times the same way, turn it into a workflow: the steps, the check on each, and which step needs a person.
一句話
好的 skill 說的是這份工作在這裡怎麼做、哪裡容易出錯,不是教科書怎麼說。一份有好幾步的工作,如果用同樣的方式手動做過大約三次,就把它變成 workflow:每一步、每一步的檢查,以及哪一步需要人。
一句话
好的 skill 讲的是这项工作在这里怎么做、容易错在哪里,而不是教科书上怎么说。一件有好几步的工作,如果已经手工按同样的做法做过大约三次,就把它变成 workflow:写明各个步骤、每一步的检查,以及哪一步需要人来定。
For leaders
- The decision: decide which routines the team repeats by hand and is ready to write down, and who owns each written skill or workflow.
- The risk: a skill that repeats what the agent already knows costs room and adds nothing. A written workflow runs the same way every time, including a wrong way, and it goes stale when how things are done here changes. I have no measured before-and-after for skills.
- The cost of doing it right: my rule of thumb is to write a routine down the third time it is done by hand (a number I chose, not tested). Designing and testing a workflow, and keeping it up to date, is the real price.
- Ask the team: "Which multi-step job have we done by hand three times, and where did the agent go wrong last time?"
給主管
- 要做的決定:決定團隊有哪些例行工作是手動重複做的、而且已經準備好寫下來,以及誰負責每一份寫好的 skill 或 workflow。
- 風險:重複 agent 本來就知道的內容的 skill,佔位子,什麼也沒加。寫好的 workflow 每次都用同樣的方式跑,包括錯的方式;而且這裡做事的方式一變,它就過期。我沒有 skill 的前後實測數字。
- 做對的成本:我的經驗法則是,一個例行工作第三次手動做的時候,就把它寫下來(這個數字是我選的,沒測過)。設計和測試 workflow,並讓它保持最新,才是真正的價錢。
- 可以問團隊:「哪一份多步驟的工作,我們手動做過三次?上一次 agent 在哪裡做錯了?」
写给管理者
- 要拍板的事:决定团队里哪些例行工作是手工重复做的、而且已经可以写下来,并决定每个写好的 skill 或 workflow 归谁管。
- 风险:重复 agent 本来就知道的东西的 skill,占地方,还什么都没加。写好的 workflow 每次都按同一种方式运行,错的方式也一样;这里的做法一变,它就过期。skill 的前后对比,我没有量过。
- 做对的代价:我的经验法则是,一件事手工做到第三次,就把它写下来(这个数字是我自己定的,没有测过)。真正的代价是设计和测试 workflow,并让它一直保持最新。
- 可以问团队:“哪件多步骤的工作我们已经手工做过三次?上一次 agent 错在哪?”
The problem
The first skill most people write is a tutorial. "How to write a SQL query." "How to do a code review." The agent read a thousand tutorials like that while it was trained. Your skill adds nothing it did not know, and it costs room in the window each time it loads.
What the agent does not know is your place. Which table is the real one and which is a leftover. Which step people forget. Which file looks unused and is read by another team. That is what you know and it does not, and it is what is most worth putting in a skill.
Two words first.
- A skill is a manual for one kind of job (see Instructions and skills).
- A workflow is a skill-sized idea one level up: a fixed order of several jobs, with a check after each and a note of where a person must decide. Think of a recipe card in a restaurant kitchen, as opposed to a cooking textbook. Careful: Anthropic uses the same word for something else, a system where code fixes the path and calls the model at set points (Building effective agents). Here a workflow is a written routine that an agent follows.
I do not have a measured before-and-after to give you for skills. The reasoning below is what I follow, and the tests at the end let you measure it yourself.
問題
大多數人寫的第一個 skill 是教學。「怎麼寫 SQL 查詢。」「怎麼做 code review。」agent 在訓練時讀過上千份這樣的教學。你的 skill 沒有加進任何它不知道的東西,而每次載入,還要佔視窗裡的位子。
agent 不知道的,是你這個地方。哪張表是真的、哪張是遺留的。哪一步人們會忘。哪個檔案看起來沒人用,其實另一個團隊在讀。這些是你知道、它不知道的,也是最值得放進 skill 的。
先說兩個詞。
- skill 是某一類工作的手冊(見指令與 skill:只載入需要的)。
- workflow 是比 skill 再高一層的想法:幾份工作的固定順序,每一份後面有檢查,並標明哪裡必須由人決定。想想餐廳廚房裡的食譜卡,而不是烹飪教科書。要小心:Anthropic 用同一個詞指別的東西,一種由程式碼固定路徑、在固定的點呼叫模型的系統(Building effective agents)。這裡的 workflow 是寫下來、讓 agent 照著做的例行流程。
關於 skill,我沒有可以給你的前後實測。下面的推理是我遵循的,最後的測試讓你自己去量。
问题
大多数人写的第一个 skill 是教程。“怎么写 SQL 查询。”“怎么做代码评审。”agent 在训练时读过上千篇这样的教程。你的 skill 没有加任何它不知道的东西,每次加载还要占窗口里的地方。
agent 不知道的,是你这里的情况。哪张表是真正在用的,哪张是遗留下来的。哪一步大家容易忘。哪个文件看起来没人用,其实另一个团队在读。这些是你知道而它不知道的,也最值得放进 skill。
先说两个词。
- skill 是针对某一类工作的手册(见指令与 skill:只加载需要的)。
- workflow 是比 skill 高一级的想法:几项工作按固定顺序排好,每一项后面有检查,并注明哪里必须由人来定。可以想成餐厅厨房里的菜谱卡,而不是烹饪教科书。注意:Anthropic 用同一个词指另一种东西,即由代码固定路径、在固定的点调用模型的系统(Building effective agents)。这里的 workflow 是 agent 照着做的、写下来的例行流程。
关于 skill,我没有量过的前后对比可以给你。下面的推理是我自己遵循的,最后的测试能让你自己去量。
How it works
The difference in one picture:
1. Write only what the agent would get wrong
For every line in a draft skill, ask: if I delete this, will the agent get something wrong or miss something? If not, delete it.
What stays:
- Your conventions. Naming, layering, where a new thing is registered.
- Defaults that are not obvious. The thing everyone on the team does without thinking about it.
- Traps. What looks right and is not.
- Your tools. The exact command, with the flag that matters.
What goes: how the language works, what a library does, anything on the first page of its documentation. Anthropic's own guide to writing skills gives a small example: a paragraph that explains what a PDF is and that you need a library to read one teaches the model what it already knows, while one line, "Use pdfplumber for text extraction", tells it the choice that was made. Their rule of thumb is "Default assumption: Claude is already very smart. Only add context Claude doesn't already have." (Skill authoring best practices)
A skill with no such line is short. That is fine. A short skill is read whole and followed.
2. A skeleton to start from
A skill is a folder. The part that matters is one file, with a header and a body:
- Header: a name, and a description that says what it does, when to use it, and the words a person would say.
- When to use it (and when not to).
- What it needs first. For example, an open task, or a tool installed.
- The steps, if the job is a fixed process. For open-ended work, give the standards to judge by instead of fixed steps: a rigid recipe breaks when the case is a little different.
- Gotchas.
Gotchas are the most valuable part. They are warnings written ahead of time, one per line: the rule in bold, then the reason. Treat them as a living list: every time the agent gets this job wrong, add one line. That is the cheapest way to improve a skill, and it is the part that improves most with use.
Examples of the shape, from an "impact analysis" skill, which finds everything a change touches before the plan is written:
- A column named only by its bare name matches everything. Search the table and the column together.
- Names built at run time are not found by any text search. Say so in the result instead of reporting "no impact".
- No hit does not mean unused: readers outside the repositories you can see are invisible. Write that, and ask who else reads it.
None of these is in a textbook. Each is something that a competent agent gets wrong the first time. The third also shows a habit worth teaching: the skill tells the agent to say what it could not see.
Scripts. If part of the job has one right answer (find every file that mentions a name, count the uses), put it in a script the skill tells the agent to run. The script gives the same answer every time at no cost in reading; the model does the part that needs judgment. That skill does this: one command in place of a run of searches, then the model sorts the hits.
Length. When a skill grows past about 200 lines, move the detail into separate files and keep the main file as the flow and the links. The detail then loads only at the step that needs it.
3. Take it from real work, not from imagination
The best source of a skill is a job you have just done and corrected. Before you write, open the last real task of this kind and ask:
- Where did the agent go wrong? Each of those is a gotcha.
- Where did you correct it? Each of those is a convention.
- What did you have to look up that it could have been told?
Write the skill from those, not from what you think a good manual should say. I have a skill that does only this: at the end of a task, it drafts what a later agent would get wrong, with the evidence from the task, and a person decides what stays. Memory covers why a person decides.
4. From skill to workflow
If you only write single skills, you can skip to "Test your own setup". The rest is for routines of many steps.
One job is a skill. A routine of several jobs is a workflow. "Every time we add a pipeline, we do these eight steps." If you do it by hand and the agent has to be told each time, that is the sign.
My rule of thumb: the third time you do the same multi-step thing, stop and write it down. One time is an accident. Two could be a coincidence. Three is a routine. I picked three myself; I have no test that shows it is the right number. A workflow pays when the routine comes back often and a missed step is costly. Against that stand the cost of designing it, testing it and keeping it up to date.
How to get a workflow without inventing it:
-
Take two or three finished examples. Real ones, already done by a person.
-
Put them side by side and replace each example's name with a placeholder. Parts that look the same in every example are the skeleton. Parts that change with the name are parameters. Parts that differ beyond the name are where judgment lives.
-
Sort every step into one of four kinds, asking in this order and stopping at the first yes:
Ask If yes, it is What to do Does it need authority (an approval, a production run, a protected file)? Human It stays with a person. Did the same inputs give the same result in the examples? Fixed A script can do it, with a test. Is it a check of a result? Check A script if a command can check it; otherwise a checklist for the model and an independent reviewer (Use subagents sparingly). Does it need to understand the requirement? Judgment The model's job, with a checklist, pointers to your documents, and the common mistakes. -
Do not design from the description alone. What people say they do and what the examples hold differ. That difference is the most useful finding. If you have no examples, say the design is a guess.
-
Write it down for approval before building anything. A workflow touches many files. A person approves the design first.
When unsure whether a step is fixed or judgment, choose judgment. Judgment can be turned into code later; code that was wrong about a judgment is harder to find.
5. What each step carries
A workflow is a chain, so each link says three things:
- In: what must be true before this step.
- Out: what exists after it, in a form the next step can read.
- Check: how it is known to be right. A command if possible.
And the steps that wait for a person say so. Two things to guard against. The workflow must not skip the approvals your setup already has. And it should leave room: write defaults and conditions ("skip when..."), not a fixed script, and say what to do when a case fits none of them.
If a workflow has more than about a dozen steps, or two different kinds of result, split it.
6. Two examples
Impact analysis (a skill with a script). Before a plan, find what a change touches. The script searches every repository for the names being changed. The skill makes the model sort the hits into must change, must check, and no effect, and requires a list of what the search cannot see. This is the case the subagents chapter mentions: once, in one case, a builder missed two references across areas, and only an independent check found them. It is one case, not a rate. A skill that does this search first moves that catch earlier.
A test guide (a workflow step that ends at a person). After a change is written back, the agent cannot run anything in the test environments; a person does. So the skill writes what to run in each environment, with expected results and what to send back. When the person brings the results, the skill judges them against the criteria written before. The point of the design is where it stops: at the person, with a clear list of what to do and what to bring back.
Test your own setup
Is it found, and does it change anything? The two tests for a single skill are in Instructions and skills. Anthropic's guide adds one habit: build the test cases before you write much, from tasks the agent got wrong without the skill, then write just enough to fix them.
Does the workflow hold? Run it on a case that is not one of your examples. Where it fails is a missing variant or a step you sorted wrongly.
原理
用一張圖看差別:
1. 只寫 agent 會做錯的
草稿 skill 裡的每一行,都問:如果我刪掉它,agent 會做錯或漏掉什麼嗎?不會,就刪掉。
留下的:
- 你的慣例。命名、分層、新東西在哪裡登記。
- 不明顯的預設。團隊裡每個人都不假思索在做的事。
- 陷阱。看起來對、其實不對的東西。
- 你的工具。確切的指令,附上要緊的那個參數。
刪掉的:語言怎麼運作、函式庫做什麼,以及文件第一頁上的任何東西。Anthropic 自己的 skill 寫作指南給了一個小例子:一段解釋 PDF 是什麼、要讀它需要函式庫的文字,教的是模型已經知道的;而一行「用 pdfplumber 抽取文字」,說的是已經做好的選擇。他們的經驗法則是「預設假設:Claude 已經非常聰明。只加 Claude 還沒有的上下文。」(Skill authoring best practices)
沒有這種行的 skill 很短。沒關係。短的 skill 會被整個讀完、也會被遵守。
2. 起步用的骨架
skill 是一個資料夾。要緊的部分是一個檔案,有檔頭和正文:
- 檔頭:名稱,和一段描述,說明它做什麼、什麼時候用,以及人會說的字。
- 什麼時候用(和什麼時候不用)。
- 先要有什麼。例如一個打開的任務,或一個裝好的工具。
- 步驟,如果這份工作是固定流程的話。開放式的工作,就給判斷用的標準,不給固定的步驟:死板的食譜遇到稍有不同的情況就壞了。
- 陷阱(gotchas)。
陷阱是最有價值的部分。它們是事先寫好的警告,一行一條:規則用粗體,然後是理由。把它們當成活的清單:每次 agent 把這份工作做錯,就加一行。這是改進 skill 最便宜的辦法,也是用得越多進步越多的部分。
形狀的例子,來自一個「影響分析」skill,它在寫計劃之前,找出一項改動碰到的所有東西:
- 只用光禿禿的欄位名稱,會對上所有東西。要把表和欄位一起搜尋。
- 在執行時才組出來的名稱,任何文字搜尋都找不到。要在結果裡說明這一點,不要回報「沒有影響」。
- 沒有命中不等於沒人用:你看不到的倉庫之外的讀取者是看不見的。把這寫下來,並問還有誰在讀。
這些都不在教科書裡。每一條都是能幹的 agent 第一次會做錯的事。第三條還顯示了一個值得教的習慣:skill 要 agent 說出它看不到什麼。
腳本。如果工作的一部分只有一個正確答案(找出所有提到某個名稱的檔案、數有幾處用到),就放進腳本,由 skill 告訴 agent 去執行。腳本每次給出同樣的答案,不花任何閱讀的成本;模型做需要判斷的那部分。那個 skill 就是這樣做的:一條指令取代一連串的搜尋,然後模型把命中的結果分類。
長度。skill 長到超過約 200 行時,把細節移到另外的檔案,主檔案只留流程和連結。這樣細節就只在需要它的那一步才載入。
3. 從真實的工作取材,不要憑想像
skill 最好的來源,是你剛做完並修正過的一份工作。動筆之前,打開最近一次這類真實的任務,問:
- agent 在哪裡做錯了?每一處都是一條陷阱。
- 你在哪裡糾正了它?每一處都是一條慣例。
- 你得去查的什麼東西,本來可以直接告訴它?
從這些寫 skill,不要從你覺得好手冊該說什麼來寫。我有一個 skill 只做這件事:在任務結束時,它起草後來的 agent 會做錯什麼,附上任務裡的證據,由人決定留下什麼。為什麼由人決定,見agent 該記住什麼。
4. 從 skill 到 workflow
如果你只寫單一的 skill,可以跳到「測一測你自己的設定」。其餘是給多步驟的例行工作的。
一份工作是 skill。幾份工作組成的例行流程是 workflow。「每次我們加一條 pipeline,就做這八步。」如果你手動做,而且每次都得告訴 agent,這就是跡象。
我的經驗法則:同樣的多步驟事情,做第三次時,停下來寫下來。一次是意外。兩次可能是巧合。三次就是例行工作。三次是我自己選的;我沒有測試顯示這是對的數字。當例行工作常常回來、漏掉一步代價又高時,workflow 才划算。和這相對的,是設計它、測試它、讓它保持最新的成本。
怎麼得到 workflow 而不用憑空發明:
-
拿兩三個做完的範例。真的,已經由人做完的。
-
把它們並排放,把每個範例的名稱換成佔位符。在每個範例裡看起來一樣的部分,是骨架。隨名稱變的部分,是參數。除了名稱之外還有不同的部分,是判斷所在的地方。
-
把每一步歸入四種之一,按這個順序問,第一個「是」就停:
問 如果是,它是 怎麼辦 它需要權限嗎(批准、正式環境的執行、受保護的檔案)? 人 留給人。 範例裡同樣的輸入給出同樣的結果嗎? 固定 腳本可以做,附上測試。 它是對結果的檢查嗎? 檢查 指令能檢查的,用腳本;否則給模型一份檢查清單,和一個獨立的 reviewer(慎用子 agent)。 它需要理解需求嗎? 判斷 這是模型的工作,附上檢查清單、指向你的文件,和常見的錯誤。 -
不要只憑描述來設計。人們說自己怎麼做,和範例裡實際有的,是不同的。這個差異是最有用的發現。如果你沒有範例,就說明這份設計是猜的。
-
在建造任何東西之前,先寫下來請人批准。workflow 會碰到很多檔案。先由人批准設計。
不確定一步是固定還是判斷時,選判斷。判斷以後可以變成程式碼;對判斷做錯了的程式碼,更難找出來。
5. 每一步帶什麼
workflow 是一條鏈,所以每個環節說三件事:
- 進:這一步之前必須成立的。
- 出:這一步之後存在的東西,形式要讓下一步讀得懂。
- 檢查:怎麼知道它是對的。可能的話用一條指令。
等人的那些步驟要明說。有兩件事要提防。workflow 不能跳過你的設定裡已有的批准。而且它應該留有餘地:寫預設和條件(「……時跳過」),不要寫固定的腳本,並說明遇到都不符合的情況該怎麼辦。
workflow 如果超過約十幾步,或有兩種不同的結果,就拆開。
6. 兩個例子
影響分析(帶腳本的 skill)。計劃之前,找出一項改動碰到什麼。腳本在每個倉庫裡搜尋要改的名稱。skill 讓模型把命中的結果分成必須改、必須檢查、沒有影響,並要求列出搜尋看不到的東西。這就是慎用子 agent那一章提到的情況:有一次,在一個案例裡,實作者漏掉了跨領域的兩處引用,只有獨立檢查找到了它們。這是一個案例,不是比率。先做這個搜尋的 skill,會把這個發現提前。
測試指南(一個終點是人的 workflow 步驟)。改動寫回去之後,agent 在測試環境裡無法執行任何東西;是由人來執行的。所以 skill 寫出在每個環境裡要跑什麼,附上預期的結果和要送回什麼。人帶著結果回來時,skill 按之前寫好的標準來判斷。這個設計的重點是它停在哪裡:停在人那裡,附上一份清楚的要做什麼、帶回什麼的清單。
測一測你自己的設定
找得到嗎?有改變什麼嗎?單一 skill 的兩個測試在指令與 skill:只載入需要的。Anthropic 的指南加了一個習慣:寫很多之前先建立測試案例,取自 agent 沒有這個 skill 時做錯的任務,然後只寫剛好能修好它們的部分。
workflow 站得住嗎?用一個不是你範例的案例去跑。失敗的地方,是缺少的變體,或是你歸錯類的步驟。
原理
一张图看区别:
1. 只写 agent 会做错的
对 skill 草稿里的每一行,问:如果我删掉它,agent 会不会做错什么或漏掉什么?不会,就删掉。
留下的是:
- 你的约定。 命名、分层、新东西在哪里注册。
- 不明显的默认做法。 团队里每个人不假思索就会做的事。
- 陷阱。 看着对、其实不对的东西。
- 你的工具。 确切的命令,带上关键的参数。
去掉的是:语言怎么工作、某个库是干什么的,以及文档第一页上就有的任何东西。Anthropic 自己的 skill 写作指南给了一个小例子:用一段话解释 PDF 是什么、读它需要一个库,是在教模型它已经知道的东西;而一行“用 pdfplumber 提取文本”,则告诉它这里做的选择。他们的经验法则是“默认假设:Claude 已经非常聪明。只补充 Claude 还没有的上下文。”(Skill authoring best practices)
没有这类行的 skill 很短。这没关系。短的 skill 会被整个读完,也会被遵守。
2. 一个起步的骨架
skill 是一个文件夹。要紧的是其中一个文件,有头部和正文:
- 头部:一个名字,和一段描述,说明它做什么、什么时候用,以及人会说的那些话。
- 什么时候用(以及什么时候不用)。
- 需要先具备什么。 比如一个打开的任务,或者装好的某个工具。
- 步骤,如果这项工作是固定流程。对开放式的工作,给出评判的标准,而不是固定的步骤:死板的菜谱,碰到稍有不同的情况就会失灵。
- 坑。
坑是最有价值的部分。 它们是提前写好的警告,一行一条:规则加粗,后面跟理由。把它们当作一份持续更新的清单:agent 每做错一次这项工作,就加一行。这是改进 skill 最便宜的办法,也是越用越好的部分。
下面几条是这类行的样子,出自一个“影响分析”skill,它在写计划之前,找出一次改动牵涉到的所有地方:
- 只用一个光秃秃的列名去搜,什么都能匹配上。要把表名和列名一起搜。
- 运行时才拼出来的名字,任何文本搜索都找不到。要在结果里写明这一点,不要报告“没有影响”。
- 没搜到不等于没人用:你看不到的仓库之外的读取方是搜不出来的。把这一点写出来,并问还有谁在读它。
这些在教科书里都找不到。每一条,都是一个称职的 agent 第一次会做错的。第三条还体现了一个值得教给它的习惯:skill 要告诉 agent 把它没看到的东西说出来。
脚本。 如果工作里有一部分只有一个正确答案(找出所有提到某个名字的文件、数一数用了几次),就把它写成脚本,让 skill 告诉 agent 去运行。脚本每次都给同样的答案,还不用花读取的成本;模型做需要判断的那一部分。上面那个 skill 就是这样:用一条命令取代一连串搜索,再由模型对搜到的结果分类。
长度。 skill 超过大约 200 行时,把细节挪到单独的文件里,主文件只留流程和链接。这样细节只在用到它的那一步才加载。
3. 从真实的工作里来,不要凭想象
skill 最好的来源,是你刚做完并纠正过的一项工作。动笔之前,打开最近一次这类真实的任务,问:
- agent 在哪里做错了?每一处都是一个坑。
- 你在哪里纠正了它?每一处都是一条约定。
- 你不得不去查的东西,有哪些本可以直接告诉它?
就从这些写 skill,不要从你觉得一份好手册该说什么来写。我有一个 skill 只做这件事:任务结束时,它起草后来的 agent 会做错什么,附上任务里的证据,由人决定留下哪些。为什么由人来定,agent 该记住什么里有讲。
4. 从 skill 到 workflow
如果你只写单个 skill,可以直接跳到“检验你自己的配置”。后面是讲多步骤的例行工作的。
一项工作是 skill。几项工作串起来的例行流程是 workflow。“每次我们加一条 pipeline,都做这八步。”如果你是手工做的,而且每次都得告诉 agent,这就是信号。
我的经验法则:同样的多步骤的事做到第三次,就停下来写下来。 一次是意外。两次可能是巧合。三次就是例行工作。三是我自己选的;没有测试表明它是对的数字。当例行工作经常回来、漏一步代价又高时,workflow 才划算。与之相对的,是设计它、测试它和让它保持最新的成本。
不用凭空发明,也能得到 workflow:
-
拿两三个已经做完的例子。 要真实的,是人已经做完的。
-
并排放在一起,把每个例子里的名字换成占位符。每个例子里看起来都一样的部分,是骨架。随名字变化的部分,是参数。除了名字之外还有差异的部分,是判断所在的地方。
-
把每一步归入四类之一,按这个顺序问,第一个回答“是”就停:
问 如果是,它就是 怎么办 它需要权限吗(审批、生产环境的运行、受保护的文件)? 人 留给人。 几个例子里,相同的输入得到了相同的结果吗? 固定 可以用脚本做,加上测试。 它是对结果的检查吗? 检查 能用命令检查的,就用脚本;否则给模型一份检查清单,再加上独立的 reviewer(慎用子 agent)。 它需要理解需求吗? 判断 是模型的活,配上检查清单、指向你的文档的指引,以及常见的错误。 -
不要只凭描述来设计。 人说他们怎么做,和例子里实际有的东西,是有差别的。这个差别是最有用的发现。如果你没有例子,就说明这个设计是猜的。
-
先写下来请人审批,再动手做任何东西。 workflow 会牵涉很多文件。要先由人批准设计。
不确定一步是固定的还是需要判断的时候,选判断。判断以后可以改成代码;对判断出了错的代码,更难找。
5. 每一步带什么
workflow 是一条链,所以每个环节要说三件事:
- 入:这一步之前必须成立什么。
- 出:这一步之后有什么,要写成下一步能读的形式。
- 检查:怎么知道它是对的。能用命令就用命令。
等人的那些步骤,要明说。有两点要防。workflow 不能跳过你的配置里已有的审批。另外它要留有余地:写默认做法和条件(“……时跳过”),不要写死脚本,并说明碰到一个都不符合的情况该怎么办。
如果一个 workflow 超过大约十几步,或者有两种不同的结果,就拆开。
6. 两个例子
影响分析(带脚本的 skill)。在做计划之前,找出一次改动牵涉到什么。脚本在所有仓库里搜要改的名字。skill 让模型把搜到的结果分成必须改、必须核对、没有影响三类,并要求列出搜索看不到的东西。这就是子 agent 那一章提到的情况:有一次,在一个案例里,开发者漏掉了跨领域的两处引用,只有独立检查才发现。那是一个案例,不是比率。先做这一搜的 skill,会把这次发现提前。
测试指南(以人为终点的 workflow 步骤)。改动写回去之后,agent 不能在测试环境里运行任何东西;由人来跑。所以 skill 写出在每个环境里该跑什么、预期结果是什么、要把什么带回来。人带着结果回来时,skill 按事先写好的标准来判断。这个设计的关键在于它在哪里停下来:停在人这里,附一份清楚的清单,说明要做什么、要带回什么。
检验你自己的配置
它能被找到吗?它改变了什么吗? 单个 skill 的两个测试在指令与 skill:只加载需要的里。Anthropic 的指南还加了一个习惯:先做测试用例,再多写东西。测试用例来自没有这个 skill 时 agent 做错的任务,然后只写刚好够修正它们的内容。
workflow 站得住吗? 拿一个不属于你那几个例子的情况去跑。失败的地方,要么是缺了一种变体,要么是你把某一步归错了类。
Costs and traps
A skill can go stale. It states how things are done here, and here changes. A skill that says to use a command that no longer exists is worse than none. Look at each one when the thing it describes changes, and give each an owner.
Wrong gotchas teach wrongly. A gotcha written from a single case can mislead in the next. Keep the reason with the rule, so a reader can judge whether it still applies.
Fixed steps cost flexibility. A tight recipe is right for a fixed process and wrong for open work. If the agent follows your steps into a case they do not fit, they were too tight.
A workflow can be wrong in a way nobody sees. It runs the same way every time, including a wrong way. The checks are there for this; give each step one.
What I did not measure. I have not compared an agent with and without a given skill across many runs. The skill tests above are a first pass, not a measurement (Run it several times says how to measure).
代價和陷阱
skill 會過期。它說的是這裡的做事方式,而這裡會變。一個說要用已經不存在的指令的 skill,比沒有還糟。它描述的東西一變,就去看一看每一個,並給每一個負責人。
錯的陷阱會教錯。根據單一案例寫的陷阱,在下一個案例可能誤導人。把理由和規則放在一起,讀的人才能判斷它是否仍然適用。
固定的步驟要付出彈性的代價。緊的食譜適合固定的流程,不適合開放的工作。如果 agent 照著你的步驟走進了它們不適用的情況,說明它們太緊了。
workflow 可能錯得沒人看得見。它每次都用同樣的方式跑,包括錯的方式。檢查就是為此而設的;每一步都給一個。
我沒量的。我沒有在很多次運行中,比較過有沒有某個 skill 的 agent。上面的 skill 測試是第一輪,不是量測(一次運行證明不了什麼說了怎麼量)。
代价和坑
skill 会过期。 它写的是这里的做法,而这里会变。一个让你用已经不存在的命令的 skill,比没有还糟。它描述的东西一变,就去看一眼,并给每个 skill 指定负责人。
错的坑会教错。 从单个案例写出来的坑,在下一个案例里可能误导人。把理由和规则放在一起,这样读的人才能判断它是否仍然适用。
固定的步骤要用灵活性换。 严格的菜谱适合固定流程,不适合开放式的工作。如果 agent 照着你的步骤走进了它们不适用的情况,说明步骤写得太死。
workflow 可能错得没人发现。 它每次都按同样的方式运行,错的方式也一样。检查就是为此而设的;每一步都要有一个。
我没量的。 我没有在很多次运行中,比较过有没有某个 skill 的 agent。上面的 skill 测试是初步的,不是量测(一次运行证明不了什么说了怎么量)。
What the industry says Industry practice
VS Code's skills documentation describes the same format and the three-stage loading, and says to write instructions that are "clear" and "specific" with step-by-step procedures where they apply. It also says plainly that discovery does not guarantee a skill is used. (Agent skills) Anthropic's skill-writing guide gives the same advice I follow: assume the model is already very smart and add only what it does not have, and challenge each paragraph with "Does this paragraph justify its token cost?". (Skill authoring best practices) It also suggests building the test cases first and keeping the skill under about 500 lines; my own limit of about 200 is stricter and is a habit, not a measured value.
業界怎麼說 業界做法
VS Code 的 skill 文件描述了同樣的格式和三階段載入,並說要把指令寫得「清楚」、「具體」,在適用的地方附上一步步的程序。它也明確說,發現機制不保證 skill 一定會被使用。(Agent skills)Anthropic 的 skill 寫作指南給的建議和我遵循的一樣:假設模型已經很聰明,只加它沒有的,並用「這一段值得它花的 token 嗎?」來質疑每一段。(Skill authoring best practices)它還建議先建立測試案例,並讓 skill 低於約 500 行;我自己約 200 行的上限更嚴,那是習慣,不是量出來的值。
业界怎么说 业界做法
VS Code 的 skill 文档描述了同样的格式和三阶段加载,并说指令要写得“清楚”“具体”,需要时给出分步的做法。它也明说,发现机制并不保证 skill 会被用上。(Agent skills)Anthropic 的 skill 写作指南给的建议,和我遵循的一样:假设模型已经非常聪明,只补充它没有的东西,并用“这一段值得它花的 token 吗?”来质疑每一段。(Skill authoring best practices)它还建议先做测试用例,并把 skill 控制在大约 500 行以内;我自己的上限大约是 200 行,更严格,是一种习惯,不是量出来的值。
When to delete it Industry practice
A gotcha goes when the model stops making the mistake, or when the code makes it impossible. Check them when you change models: some may be dead weight, and a dead gotcha only takes room. A fixed step goes when the platform does it for you. A whole workflow goes when it has not run for a long time, or when the routine itself is gone.
What stays is the habit: after a real task, look at what the agent got wrong, and write that down in the place it will be read.
什麼時候可以刪掉 業界做法
模型不再犯那個錯,或程式碼讓它不可能發生時,陷阱就可以去掉。換模型時檢查它們:有些可能已經是死重,而死掉的陷阱只佔位子。平台替你做了的固定步驟,就可以去掉。整個 workflow,在很久沒跑過、或例行工作本身消失時,可以去掉。
留下來的是習慣:做完一個真實的任務後,看 agent 做錯了什麼,把它寫在會被讀到的地方。
什么时候可以删掉 业界做法
模型不再犯那个错,或者代码让它不可能再犯时,这条坑就可以删掉。换模型时检查一遍:有的可能已经是累赘,而失效的坑只会占地方。平台替你做了固定的步骤,那一步就可以删掉。整个 workflow,在很久没有运行过,或者例行工作本身已经没有了的时候,就可以删掉。
留下的是这个习惯:做完一项真实的任务,看看 agent 做错了什么,把它写在会被读到的地方。
Try it on your own setup
No harness needed. Open your agent in your own repository and paste:
Look through the recent git history of this repository for changes that repeat the same multi-step pattern (for example, adding a new module, a new endpoint or a new job, which touches the same set of places each time). List up to three such routines with the commits that show them. For each, say which steps looked identical every time, which varied with the name, and which needed a person's decision. Say which routine is worth writing down first. Do not change any files.在你自己的環境試試
不用裝 harness。在你自己的倉庫裡打開 agent,貼上:
翻一下這個倉庫最近的 git 歷史,找出重複同樣多步驟模式的改動(例如加一個新模組、新 endpoint 或新工作,每次都碰到同一組地方)。最多列出三個這樣的例行工作,附上能顯示它們的 commit。每一個,說明哪些步驟每次看起來都一樣、哪些隨名稱變、哪些需要人來決定。說明哪個例行工作最值得先寫下來。不要改任何檔案。在你自己的环境里试试
不用装 harness。在你自己的仓库里打开 agent,粘贴:
翻看这个仓库最近的 git 历史,找出重复同一个多步骤模式的改动(比如新增一个模块、一个接口或一个任务,每次都牵涉同一批地方)。列出最多三个这样的例行工作,并附上能体现它们的提交。对每一个,说明哪些步骤每次看起来都一样,哪些随名字变化,哪些需要人来决定。说明哪个例行工作最值得先写下来。不要修改任何文件。Go deeper
- VS Code docs: Agent skills
- Anthropic: Skill authoring best practices
- In this book: Instructions and skills, Memory, Use subagents sparingly
延伸閱讀
- VS Code 文件:Agent skills
- Anthropic:Skill authoring best practices
- 本書:指令與 skill:只載入需要的、agent 該記住什麼、慎用子 agent
延伸阅读
- VS Code 文档:Agent skills
- Anthropic:Skill authoring best practices
- 本书:指令与 skill:只加载需要的、agent 该记住什么、慎用子 agent
You can stop here: that is the whole idea. The next part shows where it runs, so you can look inside.讀到這裡就夠了,這就是整個想法。下一部分告訴你它在哪裡運行,可以進去看看。读到这里就够了,核心思路就是这些。下一部分告诉你它在哪里跑,可以进去看看。
In my practice (Copilot Harness)實作实战
Copilot Harness is my open-source harness for VS Code Copilot.
Repository: https://github.com/Smars-Bin-Hu/copilot-agentic-harness
Get started: clone it, open it in VS Code, and type /harness-rookie-get-me-ready in Copilot Chat. You need Python 3.9 or later and git.
Copilot Harness 是我開源的 VS Code Copilot harness。
倉庫: https://github.com/Smars-Bin-Hu/copilot-agentic-harness
開始:clone 下來,用 VS Code 打開,在 Copilot Chat 裡輸入 /harness-rookie-get-me-ready。需要 Python 3.9 以上和 git。
Copilot Harness 是我开源的 VS Code Copilot harness。
仓库: https://github.com/Smars-Bin-Hu/copilot-agentic-harness
上手:把仓库 clone 下来,用 VS Code 打开,在 Copilot Chat 里输入 /harness-rookie-get-me-ready。需要 Python 3.9 及以上版本和 git。
Explore it in the harness
Copilot Harness ships a skill that builds new skills, a skill that designs a workflow from examples, and the two examples above. The harness can open them with you. After the setup above, type:
/harness-rookie-wondering I have read the chapter "Turn your way of working into skills". Teach me how this harness writes and tests skills (topic 3): open the skill that builds skills, then the workflow-design skill and the impact-analysis skill, and show me where their gotchas came from and how a skill is tested to be found.It teaches one small piece at a time and opens the files with you.
在 harness 裡探索
Copilot Harness 附帶一個用來做新 skill 的 skill、一個從範例設計 workflow 的 skill,以及上面那兩個例子。harness 可以和你一起打開它們。照上面的說明準備好之後,輸入:
/harness-rookie-wondering 我讀完了「把團隊的做法寫成 skill」這一章。請教我這個 harness 怎麼寫和測試 skill(主題 3):打開那個用來做 skill 的 skill,再打開設計 workflow 的 skill 和影響分析的 skill,告訴我它們的陷阱是從哪裡來的,以及怎麼測試一個 skill 找不找得到。它一次教一小塊,並和你一起打開檔案。
在 harness 里探索
Copilot Harness 自带一个用来创建新 skill 的 skill、一个根据例子设计 workflow 的 skill,以及上面那两个例子。harness 可以和你一起打开它们。按上面的说明准备好之后,输入:
/harness-rookie-wondering 我读完了“把团队的做法写成 skill”这一章。请教我这个 harness 是怎么写 skill 和测试 skill 的(主题 3):打开那个创建 skill 的 skill,再打开设计 workflow 的 skill 和影响分析的 skill,给我看它们的坑是从哪来的,以及怎么测试一个 skill 能被找到。它一次只教一小块,并和你一起打开文件。