> Harness EngineeringHarness EngineeringHarness Engineering The engineering outside the model模型之外的工程模型之外的工程

3.3

Instructions and skills指令與 skill:只載入需要的指令与 skill:只加载需要的

This chapter assumes you have used an AI coding agent, and read the context budget (everything the agent reads shares one window of limited size).

讀這一章,請先用過 AI 寫程式的 agent,並讀過上下文是一份預算(agent 讀的所有東西共用一個大小有限的視窗)。

读这一章,需要你用过 AI 编程 agent,并且读过上下文是一份预算(agent 读到的所有东西共用一个大小有限的窗口)。

The Knowledge經驗分享经验分享

In one sentence

Load the fewest rules by default and read the rest only when needed. A skill is a manual read on demand, and like any written rule it is not enforced.

一句話

預設只載入最少的規則,其餘的在需要時才讀。skill 是一本按需要才讀的手冊,而且和任何寫下來的規則一樣,不會被強制執行。

一句话

默认只加载最少的规则,其余的需要时再读。skill 是按需阅读的手册,和任何写下来的规则一样,它不是强制执行的。

For leaders

  • The decision: keep the always-loaded rules few, and decide who owns the rule files and cuts what is no longer needed.
  • The risk: a long rule file is followed less well than a short one, and two files that disagree make the model pick one. A rule in a file is still a request: the model can do otherwise. Anything that must hold goes into code. I have no measured case of an ignored rule to quote.
  • The cost of doing it right: an owner and a regular trim of the rule files. Cutting lines the agent would get right anyway costs little; in my own files I usually saw nothing get worse, but I have not tested this systematically.
  • Ask the team: "Which lines in our always-loaded file would the agent get wrong without them, and who owns that file?"

給主管

  • 要做的決定:讓一直載入的規則保持很少,並決定誰負責規則檔、誰去剪掉不再需要的。
  • 風險:長的規則檔比短的更不容易被遵守,兩個互相矛盾的檔案會讓模型挑一個。寫在檔案裡的規則仍然只是請求:模型可以不照做。一定要成立的東西,要放進程式碼。我手上沒有可以引用的、規則被無視的實測案例。
  • 做對的成本:一個負責人,和定期修剪規則檔。剪掉 agent 本來就會做對的行,成本很低;在我自己的檔案裡,我通常沒看到有什麼變差,但我沒有系統地測過。
  • 可以問團隊:「我們一直載入的檔案裡,哪幾行是 agent 沒有它們就會做錯的?誰負責那個檔案?」

写给管理者

  • 要拍板的事:始终加载的规则要少,并决定谁负责规则文件、谁来删掉不再需要的内容。
  • 风险:长的规则文件,agent 遵守得不如短的好;两个文件说法不一致,模型会挑其中一个。写在文件里的规则仍然只是请求:模型可以不照做。必须成立的事要写进代码。我没有实测过的“规则被无视”的案例可以引用。
  • 做对的代价:一个负责人,加上定期精简规则文件。删掉 agent 本来就会做对的那些行,代价很小;在我自己的文件里,我一般没看到有什么变差,但我没有系统地测过。
  • 可以问团队:“我们始终加载的文件里,哪些行是去掉之后 agent 就会做错的?这个文件归谁管?”

The problem

The natural way to teach an agent your project is to write everything down in one file: the rules, the conventions, the warnings, the how-to for every job. Each time the agent makes a mistake, you add a line. After a few weeks the file is long, and the agent follows it less well than when it was short.

Two things go wrong. They are the subject of this chapter.

  • Everything is paid for every turn. The file sits in the window all the time, whether or not this job needs it. A rule about database migrations takes room while you fix a typo. This room is the same budget that the context budget is about; what it costs per turn is in Models and cost.
  • More rules means each rule is followed less. Long files make rules compete. Two lines may disagree; an important line is lost among small ones. The docs of both Claude Code and VS Code advise keeping instruction files short, and Claude Code's warns that when two instructions contradict each other the model may pick one arbitrarily.

Three words first.

  • Instructions are rule files written for the agent to read. Some are loaded in every conversation. Others are loaded only when the agent works on certain files.
  • A skill is a folder with a manual for one kind of job. The agent reads the manual when the job comes up, not before.
  • Progressive disclosure is the idea behind both: show the agent a little, and let it read more only when it needs more. Like a shop with a menu at the door and the full recipe in the kitchen. Anthropic names it "the core design principle that makes Agent Skills flexible and scalable" (Equipping agents for the real world with Agent Skills).

I have no measured case of an ignored rule to quote, so this chapter gives the reasoning and the checks.

問題

教 agent 認識你的專案,最自然的辦法是把一切都寫進一個檔案:規則、慣例、警告、每份工作的做法。agent 每犯一次錯,你就加一行。幾個星期後,檔案很長,agent 遵守它的程度比它還短的時候差。

有兩件事出了問題。它們是這一章的主題。

  • 每一輪都要為所有東西付錢。這個檔案一直在視窗裡,不管這份工作需不需要。你在改一個錯字,資料庫遷移的規則卻佔著位子。這個位子就是上下文是一份預算講的那份預算;每一輪要花多少,在選模型:算的是每次成功的成本。
  • 規則越多,每一條被遵守的程度越低。長的檔案讓規則互相競爭。兩行可能互相矛盾;要緊的一行淹沒在小的之間。Claude Code 和 VS Code 的文件都建議讓指令檔保持簡短,Claude Code 的還警告,兩條指令互相矛盾時,模型可能隨意挑一條。

先說三個詞。

  • 指令是寫給 agent 讀的規則檔。有些在每個對話裡都載入。其他的只在 agent 處理特定檔案時才載入。
  • skill 是一個資料夾,裡面是某一類工作的手冊。agent 在這份工作出現時才讀手冊,不是事先讀。
  • 漸進式揭露(progressive disclosure)是兩者背後的想法:先給 agent 看一點,需要更多時才讓它多讀。就像一家店,門口有菜單,完整的食譜在廚房裡。Anthropic 稱它是「讓 Agent Skills 靈活、可擴展的核心設計原則」(Equipping agents for the real world with Agent Skills)。

我手上沒有可以引用的、規則被無視的實測案例,所以這一章給的是推理和檢查的辦法。

问题

教 agent 了解你的项目,最自然的办法是把所有东西写进一个文件:规则、约定、警告,以及每种工作的做法。agent 每犯一次错,你就加一行。几周之后文件变得很长,agent 遵守它的程度反而不如以前文件短的时候。

出了两个问题。它们是这一章的主题。

  • 每一轮都要为所有内容付费。 这个文件一直放在窗口里,不管这项工作需不需要它。你在改一个错别字,一条关于数据库迁移的规则也在占着地方。这个地方就是上下文是一份预算讲的那份预算;每一轮要花多少,在选模型:看每次成功的成本里。
  • 规则越多,每条规则被遵守得越差。 长文件会让规则互相竞争。两行可能互相矛盾;重要的一行淹没在细小的几行里。Claude Code 和 VS Code 的文档都建议把指令文件写短,Claude Code 的文档还警告说,两条指令互相矛盾时,模型可能会随便挑一条。

先说三个词。

  • 指令是写给 agent 读的规则文件。有的在每次对话里都加载。有的只在 agent 处理某些文件时才加载。
  • skill 是一个文件夹,里面有针对某一类工作的手册。agent 在这项工作出现时才读手册,不会提前读。
  • 渐进式披露是这两者背后的思路:先给 agent 看一点,需要更多时再让它去读。就像一家店,门口放菜单,完整的菜谱在厨房里。Anthropic 称它是“让 Agent Skills 灵活、可扩展的核心设计原则”(Equipping agents for the real world with Agent Skills)。

我没有实测过的“规则被无视”的案例可以引用,所以这一章讲的是推理和检查的办法。

How it works

1. Three places for a rule

Where you put a rule decides when it costs room and when the agent sees it.

always loaded rules all need loaded by file rules per file type read on demand skills and notes costs every turn costs only when used Put each rule in the cheapest place that still reaches it. Write it once. Elsewhere, keep a link and one sentence.
Three places for written guidance. The further right, the less it costs when it is not needed, and the more it depends on the agent choosing to read it.
  • Always loaded. A short file in the root of the repository, read in every conversation. Only the rules that every job needs go here: the safety limits, how to start, what to do when something is refused. In my setup this is one short page. If a rule is needed for one job in ten, it does not belong here.
  • Loaded by file. Rules that apply to one kind of file. In VS Code, an instruction file has a header line, applyTo, with a pattern like "all files under this folder". The rules load only when the agent opens a file that matches. Rules for how to write a skill are loaded when it opens a skill file, and cost nothing when it edits a pipeline. Here is the top of one such file:
An instruction file that loads only for skill files: the applyTo line is the pattern.
---
description: 'Guidelines for creating high-quality Agent Skills for GitHub Copilot'
applyTo: '.github/skills/**/SKILL.md'
---
  • Read on demand. Everything else: long how-tos, rarely needed details. This is where skills and reference notes go. The agent reads them when the job calls for them.

A fourth way: a hook (a small program the platform runs at fixed moments; see Hooks) can put a few lines at the top of every message you send, to repeat a rule near the point of use. Keep it to a few lines, or you rebuild the long file.

The question for every rule is: how often is this needed, and what happens if the agent misses it? Needed every time and costly to miss: always loaded. Needed for one kind of file: by file. Needed for one job: a skill.

2. A skill loads in three levels

A skill is a folder. The main file, SKILL.md, has a header (a name and a description) and a body (the manual). Next to it can be longer notes, scripts and templates.

level what is in the window when 1. Menu name + one description always, every skill 2. Manual the whole SKILL.md when the request fits 3. Extras scripts, notes, templates if the manual says
  1. Level 1: every skill shows only a name and a description, all the time. This is cheap, and it is all the agent has when it chooses.
  2. Level 2: when a request fits a description, the whole manual is read into the window.
  3. Level 3: files next to the manual are read only if the manual points at them and the step needs them.
A skill costs a line until it is used, a page when it is used, and more only if the job needs it. The description decides whether level 2 ever happens.

The agent does not see all of it at once.

  1. Always, the name and description of every skill. This is the menu. It is small, but it is paid for every turn, for every skill you have installed.
  2. When the request fits a description, the whole manual. The agent decides this itself, or you type the skill's name.
  3. Only when the manual points to them, the extra files. A long reference or a script is read at the step that needs it.

So you can install many skills without filling the window.

The description decides whether the skill is ever found. At level 1 the description is all the agent has. A vague one ("helps with code quality") never matches anything. A good description says three things: what the skill does, when to use it ("use when..."), and the words a person would actually say when they need it. The platform limits its length, and a wordy one costs room for every other skill too.

Even a good description does not guarantee use. VS Code's documentation says plainly that discovery makes skills available but does not guarantee the model uses one. So test it (below).

A menu can grow too long. With a few dozen skills, the menu is a real cost and many are never chosen. One answer is to keep the skills of a single business area out of the menu until the task is about that area.

3. One rule, one source

If the same rule is written in three files, a change misses one of them, and the agent reads three versions that slowly differ. Write a rule in one place. Other places hold a link and one sentence. A rule you have to restate everywhere is a sign the structure is wrong. Rule files are shared code, so give them an owner who cuts the lines that are no longer needed.

4. Why a written rule is ignored

A rule can be loaded and still not followed. The usual causes:

  1. The file is too long. Ask of each line: would the agent get it wrong without it? If not, delete the line.
  2. Rules conflict. Two files say different things. The model picks one, and not always the one you want. VS Code's docs say instruction sources are additive and that you should not depend on file order to settle a conflict. So conflicts are your job to remove: search for them, and fix the wording so only one version remains.
  3. The rule is far from where it applies. It was in the first message, now thousands of lines up. A rule-by-file or a hook reminder puts it nearer.
  4. It has no reason. "Never do X" is easy to rationalise away. "Never do X, because Y breaks" lets the model apply the idea to cases you did not list.
  5. It is a request. This is the deepest cause. Whatever you write in a file is read by the model, and the model can do otherwise. The Claude Code docs put it plainly: the memory files are "context, not enforced configuration", and to block an action regardless of what the model decides, use a hook. The text of a skill is the same. It makes the work go smoothly; it does not make the wrong thing impossible. A skill's header may carry stronger settings on some platforms, and you should check what they do. In Claude Code, for example, allowed-tools only pre-approves tools and does not restrict them, and a skill can register hooks, which are code (Skills).

For the fifth, the fix is not better wording. A rule that must hold goes into code. That choice is the subject of A rule in a prompt is a request. The text then only has to explain why, so the agent does not try again to get around the refusal. In my setup a rule that matters has both layers: the text teaches, the code stops.

5. One more choice: language

If you work in more than one language, I keep one copy of the rules and skills, in English, and tell the model which language to answer in. A second copy of prose slowly drifts from the first. That is my choice; the principle is only to have one copy.

Test your own setup

Three questions for any rule you add:

  1. How often is this needed? If rarely, it does not go in the always-loaded file.
  2. Is it already written somewhere? If so, link to it.
  3. If the agent ignores it, what happens? If the answer is "something bad that cannot be undone", it is not a text job.

A test you can run today, with no extra setup. Look at your always-loaded file. For every line, ask whether the agent would get it wrong without it. Cut every line that fails. Then run the same task as before and see whether anything got worse. When I have cut lines from my own rules file, I usually saw nothing get worse. I have not tested this systematically.

Test that a skill is found. Write the requests first, in the words a person would use, not the words of the description: three ways of asking for the job, and two neighbouring requests that should not trigger it. Open a new chat for each (an old chat may already hold the skill) and do not type the skill's name. Then look at which skills were loaded. Use the platform's log if it has one, since what the agent says is not evidence. If it did not load, the description lacks the user's words. If it loaded when it should not, the description is too wide.

Test that a skill changes anything. Run the same task twice in new chats, with and without the skill. If you cannot see a difference, cut the lines that make none. The agent already knew them.

原理

1. 規則的三個位置

規則放在哪裡,決定它什麼時候佔位子、agent 什麼時候看得到。

每次都載入 每件事都需要的少數規則 依檔案載入 只管某一種檔案的規則 用到才讀 skill 和筆記 每一輪都花錢 用到才花錢 每條規則放在還找得到它的最便宜的地方。 只寫一次。別處放連結和一句話。
書面指引的三個位置。越往右,不需要時越省,但越依賴 agent 自己選擇去讀。
  • 一直載入。倉庫根目錄裡一個簡短的檔案,每個對話都讀。只有每份工作都需要的規則放在這裡:安全限制、怎麼開始、被拒絕時該怎麼辦。在我的設定裡,它只有短短一頁。如果一條規則十份工作裡只有一份需要,它就不屬於這裡。
  • 依檔案載入。只適用於某一類檔案的規則。在 VS Code 裡,指令檔有一行檔頭 applyTo,內容是像「這個資料夾底下所有檔案」這樣的模式。只有 agent 打開符合的檔案時,規則才載入。寫 skill 的規則,在它打開 skill 檔案時載入,編輯 pipeline 時不佔任何位子。下面是這樣一個檔案的開頭:
只在處理 skill 檔案時載入的指令檔:applyTo 那一行就是模式。
---
description: 'Guidelines for creating high-quality Agent Skills for GitHub Copilot'
applyTo: '.github/skills/**/SKILL.md'
---
  • 按需要才讀。其他一切:很長的做法說明、很少用到的細節。skill 和參考筆記放在這裡。工作需要時,agent 才去讀。

第四種方式:hook(平台在固定時刻執行的小程式;見 Hooks:每次呼叫都會經過的執行點)可以在你送出的每則訊息最前面加上幾行,在用到的地方重複一條規則。只放幾行,不然你又重建了那個長檔案。

對每一條規則的問題是:這條多常需要?agent 漏掉了會怎樣?每次都需要、漏掉代價高:一直載入。只有某一類檔案需要:依檔案載入。只有某一份工作需要:skill。

2. skill 分三層載入

skill 是一個資料夾。主檔案 SKILL.md 有一段檔頭(名稱和描述)和一段正文(手冊)。旁邊可以放更長的筆記、腳本和範本。

層 視窗裡有什麼 什麼時候 1. 目錄 名字 + 一句描述 每個 skill 都一直在 2. 說明書 整份 SKILL.md 需求對得上時 3. 附帶檔案 腳本、長筆記、範本 說明書叫它讀才讀
  1. 第 1 層:每個 skill 一直只露出名字和描述。成本很低,agent 挑選時手上也只有這個。
  2. 第 2 層:需求對上某個描述時,整份說明書才讀進視窗。
  3. 第 3 層:說明書旁邊的檔案,只有說明書指到、而且這一步用得到時才讀。
一個 skill 沒用到時只佔一行,用到時佔一頁,工作需要時才再多一點。描述決定第 2 層會不會發生。

agent 不會一次看到全部。

  1. 一直都在的,是每個 skill 的名稱和描述。這是菜單。它很小,但你裝了多少個 skill,每一輪就要為它們付多少錢。
  2. 請求符合某個描述時,載入整本手冊。這是 agent 自己決定的,或者你輸入 skill 的名稱。
  3. 只有手冊指向時,才載入額外的檔案。很長的參考資料或腳本,在需要它的那一步才讀。

所以你可以裝很多 skill,而不會塞滿視窗。

描述決定 skill 到底找不找得到。在第 1 層,描述是 agent 手上全部的東西。含糊的描述(「幫助提升程式碼品質」)永遠對不上任何東西。好的描述說三件事:這個 skill 做什麼、什麼時候用(「use when……」),以及人真的需要它時會說的那些字。平台對長度有限制,而囉嗦的描述也會佔掉其他每個 skill 的位子。

就算描述很好,也不保證會用。VS Code 的文件明確說,發現機制讓 skill 可以被用到,但不保證模型會用某一個。所以要測(見下面)。

菜單也可能太長。有幾十個 skill 時,菜單是一筆實實在在的成本,而且很多從不會被選到。一個辦法是,把單一業務領域的 skill 擋在菜單之外,直到任務和這個領域有關。

3. 一條規則,一個來源

同一條規則如果寫在三個檔案裡,改的時候會漏掉其中一個,agent 讀到三個慢慢分歧的版本。規則只寫在一個地方。其他地方放一個連結和一句話。一條規則如果得到處重述,說明結構錯了。規則檔是共用的程式碼,所以要給它們一個負責人,由他剪掉不再需要的行。

4. 寫下來的規則為什麼會被無視

規則載入了,仍然可能沒被遵守。常見的原因:

  1. 檔案太長。對每一行問:沒有它,agent 會做錯嗎?不會,就刪掉這一行。
  2. 規則互相衝突。兩個檔案說的不同。模型挑一個,而且不一定是你要的那個。VS Code 的文件說,指令的來源是疊加的,不要靠檔案的順序來解決衝突。所以消除衝突是你的工作:去搜尋,並修改措辭,只留下一個版本。
  3. 規則離適用的地方很遠。它在第一則訊息裡,現在在幾千行之上。依檔案載入的規則或 hook 的提醒,可以把它放得近一點。
  4. 它沒有理由。「絕對不要做 X」很容易被繞過去。「絕對不要做 X,因為 Y 會壞掉」,讓模型能把這個想法用在你沒列出來的情況上。
  5. 它只是請求。這是最根本的原因。你寫在檔案裡的任何東西,都是模型去讀的,而模型可以不照做。Claude Code 的文件說得很直白:memory 檔是「上下文,不是強制執行的設定」,不管模型怎麼決定,想擋掉某個動作,就用 hook。skill 的文字也一樣。它讓工作進行得順利;它不讓錯的事不可能發生。在某些平台上,skill 的檔頭可以帶更強的設定,你應該去查它們做什麼。例如在 Claude Code 裡,allowed-tools 只是預先批准工具,並不限制工具,而且 skill 可以註冊 hook,那是程式碼(Skills)。

對第五點,補救不是更好的措辭。一條必須成立的規則要放進程式碼。這個選擇是提示裡的規則只是請求的主題。這時文字只需要解釋為什麼,免得 agent 再試著繞過那個拒絕。在我的設定裡,要緊的規則有兩層:文字負責教,程式碼負責擋。

5. 還有一個選擇:語言

如果你用不止一種語言工作,我只留一份規則和 skill,用英文寫,再告訴模型用哪種語言回答。第二份散文,會慢慢和第一份漂開。這是我的選擇;原則只是只有一份。

測一測你自己的設定

你加的每一條規則,都問這三個問題:

  1. 這條多常需要?很少的話,就不放進一直載入的檔案。
  2. 別處已經寫過了嗎?有的話,連過去。
  3. agent 無視它會怎樣?答案如果是「很糟、而且無法挽回的事」,那就不是文字能做的事。

今天就能做、不用額外設定的測試。看你一直載入的檔案。每一行都問:沒有它,agent 會做錯嗎?把不通過的行都剪掉。然後跑和之前一樣的任務,看有沒有什麼變差。我從自己的規則檔剪掉一些行時,通常沒看到什麼變差。我沒有系統地測過。

測 skill 找不找得到。先把請求寫好,用人會說的字,不是描述裡的字:三種要求這份工作的說法,和兩個相鄰、不該觸發它的請求。每一個都開一個新的對話(舊的對話可能已經載入了這個 skill),而且不要輸入 skill 的名稱。然後看哪些 skill 被載入了。平台有紀錄的話就用紀錄,因為 agent 自己說的不算證據。沒載入,說明描述缺少使用者的字。不該載入時載入了,說明描述太寬。

測 skill 有沒有改變什麼。同一個任務在新的對話裡跑兩次,有 skill 和沒有 skill 各一次。看不出差別的話,就剪掉那些沒有差別的行。agent 本來就知道它們。

原理

1. 规则的三个存放位置

规则放在哪里,决定了它什么时候占地方,以及 agent 什么时候看得到它。

始终加载 每件事都需要的少数规则 按文件加载 只管某一类文件的规则 按需阅读 skill 和笔记 每一轮都花钱 用到才花钱 每条规则放在还够得着它的最便宜的地方。 只写一次。别处放链接和一句话。
书面指引的三个位置。越往右,不需要时越省,但越依赖 agent 自己选择去读。
  • 始终加载。 仓库根目录里的一个简短文件,每次对话都会读。只有每项工作都需要的规则才放这里:安全底线、怎么开始、被拒绝时该怎么办。在我的配置里,这只有短短一页。如果一条规则十项工作里只有一项要用,它就不属于这里。
  • 按文件加载。 只适用于某一类文件的规则。在 VS Code 里,指令文件的头部有一行 applyTo,写一个模式,比如“这个文件夹下的所有文件”。只有 agent 打开匹配的文件时,这些规则才会加载。怎么写 skill 的规则,在它打开 skill 文件时加载;它改 pipeline 时,一点代价也没有。下面是这样一个文件的开头:
一个只对 skill 文件加载的指令文件:applyTo 那一行就是匹配模式。
---
description: 'Guidelines for creating high-quality Agent Skills for GitHub Copilot'
applyTo: '.github/skills/**/SKILL.md'
---
  • 按需阅读。 其余的一切:长的操作指南、很少用到的细节。skill 和参考笔记就放在这里。工作需要时,agent 才去读。

还有第四种办法:hook(平台在固定时刻运行的小程序,见 Hook:每次调用都会经过的执行点)可以在你发的每条消息的开头加上几行,在用到规则的地方附近重复一下它。只加几行,不然又变回了那个长文件。

对每条规则,要问的问题是:这条规则多久用一次?agent 漏掉它会怎样? 每次都要用、漏掉代价大:始终加载。只有某一类文件要用:按文件加载。只有某项工作要用:放进 skill。

2. skill 分三级加载

skill 是一个文件夹。主文件 SKILL.md 有头部(名字和描述)和正文(手册)。旁边可以放更长的笔记、脚本和模板。

级 窗口里有什么 什么时候 1. 菜单 名字 + 一句描述 每个 skill 都一直在 2. 手册 整份 SKILL.md 需求对得上时 3. 附带文件 脚本、笔记、模板 手册指到才读
  1. 第 1 级:每个 skill 一直只露出名字和描述。成本很低,agent 挑选时手上也只有这个。
  2. 第 2 级:需求对上某个描述时,整份手册才读进窗口。
  3. 第 3 级:手册旁边的文件,只有手册指到、而且这一步用得到时才读。
一个 skill 没用到时只占一行,用到时占一页,工作需要时才再多一点。描述决定第 2 级会不会发生。

agent 不会一次看到全部内容。

  1. 始终在的,是每个 skill 的名字和描述。 这是菜单。它不大,但每一轮都要付费,你装了多少个 skill 就付多少份。
  2. 需求对得上某个描述时,才读整份手册。 这由 agent 自己决定,或者你直接输入 skill 的名字。
  3. 只有手册指到时,才读额外的文件。 长的参考资料或脚本,要等到用得上它的那一步才读。

所以你可以装很多 skill,而不会把窗口填满。

描述决定这个 skill 能不能被找到。 在第 1 级,agent 手上只有描述。含糊的描述(“帮助提升代码质量”)什么也匹配不上。好的描述要说三件事:这个 skill 做什么,什么时候用(“在……时使用”),以及人真正需要它时会说的那些话。平台对长度有限制,啰嗦的描述还会占掉其他所有 skill 的地方。

即使描述写得好,也不保证会被用上。VS Code 的文档明说,发现机制只是让 skill 可用,并不保证模型会用。所以要测一下(见下面)。

菜单也会太长。 有几十个 skill 时,菜单就是一笔实实在在的开销,而且很多 skill 永远不会被选中。一种办法是:任务不涉及某个业务领域时,不把这个领域的 skill 放进菜单。

3. 一条规则,一个来源

同一条规则如果写在三个文件里,改的时候总会漏掉一个,agent 读到的是三个慢慢变得不一样的版本。一条规则只写在一个地方。别处只放一个链接和一句话。一条规则如果得到处重复,说明结构不对。规则文件是共用的代码,所以要有人负责,把不再需要的行删掉。

4. 写下来的规则为什么会被无视

规则可能已经加载了,却没被遵守。常见的原因:

  1. 文件太长。 对每一行问:没有它,agent 会做错吗?不会,就删掉这一行。
  2. 规则冲突。 两个文件说的不一样。模型挑一个,而且不一定是你想要的那个。VS Code 的文档说,各个指令来源是叠加的,不要靠文件顺序来解决冲突。所以消除冲突是你的活:去搜,改措辞,让只剩一个版本。
  3. 规则离用到它的地方太远。 它在第一条消息里,现在已经在几千行之前。按文件加载的规则,或者 hook 的提醒,能让它离得近一点。
  4. 没写理由。 “绝对不要做 X”很容易被绕过去。“绝对不要做 X,因为 Y 会坏掉”,则能让模型把这个道理用到你没列出的情况上。
  5. 它是请求。 这是最根本的原因。你写在文件里的任何东西,都是模型去读的,而模型可以不照做。Claude Code 的文档说得很直白:记忆文件是“上下文,不是强制执行的配置”,想不管模型怎么决定都拦住某个动作,就用 hook。skill 的正文也一样。它让工作顺畅,但不会让错事无法发生。在有的平台上,skill 的头部可以带更强的设置,要查一下它们到底做什么。比如在 Claude Code 里,allowed-tools 只是预先批准工具,并不限制工具,而且 skill 可以注册 hook,那是代码(Skills)。

对第 5 条,办法不是把措辞写得更好。必须成立的规则要写进代码。这个选择是提示里的规则只是请求的主题。到那时,文本只需要解释为什么,这样 agent 就不会再想办法绕过拒绝。在我的配置里,重要的规则两层都有:文本负责教,代码负责拦。

5. 再说一个选择:语言

如果你用不止一种语言工作,我的做法是规则和 skill 只留一份,用英文写,再告诉模型用哪种语言回答。散文的第二份副本会慢慢和第一份对不上。这是我的选择;原则只是只留一份。

检验你自己的配置

对你添加的任何规则,问三个问题:

  1. 这条多久用一次?如果很少,它就不放进始终加载的文件。
  2. 别处已经写过了吗?如果写过,就链接过去。
  3. 如果 agent 无视它,会怎样?如果答案是“发生了无法撤销的坏事”,那就不是文本能解决的事。

今天就能做的测试,不需要额外配置。 看你那份始终加载的文件。对每一行,问:没有它,agent 会做错吗?把不满足的行都删掉。然后跑和之前一样的任务,看有没有变差。我从自己的规则文件里删过行,一般没看到有什么变差。我没有系统地测过。

测试 skill 能不能被找到。 先把请求写好,用人真正会说的话,而不是描述里的话:三种提出这项工作的说法,再加两个相邻的、不该触发它的请求。每个请求开一个新对话(旧对话里可能已经带着这个 skill),并且不要输入 skill 的名字。然后看加载了哪些 skill。如果平台有日志,就用日志,因为 agent 自己怎么说不算证据。如果没加载,说明描述里缺用户会说的词。如果不该加载时加载了,说明描述太宽。

测试 skill 有没有改变什么。 同一个任务,在新对话里各跑一次,一次带 skill,一次不带。如果看不出区别,就把没起作用的行删掉。agent 本来就知道它们。

Costs and traps

Splitting has a price. A rule in a skill is only read if the skill is found. A rule that matters but sits in a skill with a weak description may never be read. That is the cost of saving room. If missing it is costly, keep it in a place that loads.

A skill is not a setting. It depends on the model choosing it. The same request can load it once and not the next time.

More skills, harder choice. Even a good description may be confused with its neighbour. Keep each one narrow and say what it is not for.

Hooks that inject text add up. Each line is repeated on every message. The Claude Code docs suggest under about 200 lines for a project file; that is a rule of thumb, not a measured limit. Measure your own.

代價和陷阱

拆開是有代價的。skill 裡的規則,只有 skill 被找到時才會被讀。一條要緊的規則,放在描述很弱的 skill 裡,可能永遠不會被讀。這是省位子的代價。漏掉的代價高的話,就把它留在會載入的地方。

skill 不是設定。它靠模型去選它。同一個請求,這次可能載入它,下次就不載入。

skill 越多,越難選。就算是好的描述,也可能和它的鄰居混淆。每一個都保持狹窄,並寫明它不是做什麼的。

注入文字的 hook 會累加。每一行都會在每則訊息裡重複。Claude Code 的文件建議專案檔低於約 200 行;那是經驗法則,不是量出來的限制。量你自己的。

代价和坑

拆分是有代价的。 skill 里的规则,只有 skill 被找到才会被读到。一条重要的规则,如果放在描述很弱的 skill 里,可能永远不会被读到。这就是省地方的代价。如果漏掉的代价很高,就放在会加载的地方。

skill 不是设置。 它依赖模型选中它。同一个请求,这次可能加载它,下次就不加载了。

skill 越多,选择越难。 即使描述写得好,也可能和相邻的 skill 混淆。每个都要写得窄,并说清它不是干什么的。

注入文本的 hook 会累积。 每一行在每条消息里都会重复。Claude Code 的文档建议一个项目文件不超过 200 行左右;这是经验法则,不是量出来的上限。要量你自己的。

What the industry says Industry practice

  • VS Code has the three-level loading for skills: it reads the name and description first, loads the body "once the skill is relevant", and reads other files "only when it references them". It also says that discovery "does not guarantee that it invokes a skill for every relevant prompt". For instruction files it advises to "keep your instructions short and self-contained", to "include the reasoning behind rules", and says the sources are "additive". (Agent skills, Custom instructions)
  • Anthropic describes the same three levels for Agent Skills: the name and description first, the body when the skill applies, linked files only as needed. (Equipping agents for the real world with Agent Skills)
  • Claude Code suggests keeping each memory file under 200 lines, moving part-of-the-code rules into files that load only for matching paths, and removing contradictions. It treats them as "context, not enforced configuration". (How Claude remembers your project)

The two platforms use the same shape: always-on file, path-scoped rules, on-demand skills. The idea is the same across tools, so what you build here moves with you.

業界怎麼說 業界做法

  • VS Code 對 skill 也有三層載入:先讀名稱和描述,「skill 相關時」才載入正文,其他檔案「只有在被引用時」才讀。它還說,發現機制「不保證每個相關的 prompt 都會呼叫某個 skill」。對於指令檔,它建議「讓你的指令簡短而獨立」「附上規則背後的理由」,並說來源是「疊加的」。(Agent skills、Custom instructions)
  • Anthropic 為 Agent Skills 描述了同樣的三層:先是名稱和描述,skill 適用時載入正文,連結的檔案只在需要時才載入。(Equipping agents for the real world with Agent Skills)
  • Claude Code 建議每個 memory 檔保持在 200 行以下,把屬於程式碼某一部分的規則移到只在路徑符合時才載入的檔案,並移除矛盾。它把這些當成「上下文,不是強制執行的設定」。(How Claude remembers your project)

兩個平台用的是同一個形狀:一直開著的檔案、依路徑載入的規則、按需要才讀的 skill。想法在各個工具之間是一樣的,所以你在這裡做的東西可以帶著走。

业界怎么说 业界做法

  • VS Code 对 skill 有三级加载:先读名字和描述,“一旦这个 skill 相关”才加载正文,其他文件“只有被引用时”才读。它还说,发现机制“不保证对每个相关的 prompt 都调用 skill”。对于指令文件,它建议“让你的指令保持简短、自成一体”,“写明规则背后的理由”,并说各个来源是“叠加”的。(Agent skills、Custom instructions)
  • Anthropic 对 Agent Skills 描述了同样的三级:先是名字和描述,skill 适用时再读正文,链接的文件只在需要时才读。(Equipping agents for the real world with Agent Skills)
  • Claude Code 建议每个记忆文件控制在 200 行以内,把只关系到部分代码的规则移到只对匹配路径加载的文件里,并去掉互相矛盾的地方。它把这些文件视为“上下文,不是强制执行的配置”。(How Claude remembers your project)

两个平台用的是同一种结构:始终开启的文件、按路径划分的规则、按需的 skill。各个工具的思路是一样的,所以你在这里搭的东西可以带着走。

When to delete it Industry practice

The by-hand parts that the platform may take over: listing only the skills of the current area, and cutting a long menu. If the platform learns to load skills by relevance better, the area trick can go.

The reasoning does not retire. A bigger window does not make a long rule file better; it only lets you hold more before the problem shows up. And no loading scheme makes a written rule enforced. I would look again if a platform could show, on my own tasks, that long rule files are followed as well as short ones.

什麼時候可以刪掉 業界做法

平台可能接手的手動部分:只列出目前領域的 skill,以及剪短過長的菜單。如果平台學會更好地按相關性載入 skill,領域這個辦法就可以不用了。

道理不會退役。更大的視窗不會讓長的規則檔變好;它只是讓你在問題出現之前能放更多。而且沒有任何載入方式,能讓寫下來的規則變成強制執行。如果有平台能在我自己的任務上證明,長的規則檔被遵守的程度和短的一樣好,我會再看一次。

什么时候可以删掉 业界做法

平台可能接手的手动部分:只列出当前领域的 skill,以及削减过长的菜单。如果平台学会了更好地按相关性加载 skill,按领域取舍的办法就可以去掉。

这套道理不会过时。窗口更大,也不会让长的规则文件变好;它只是让你在问题冒出来之前能装更多。而且没有哪种加载方案能让写下来的规则变成强制执行的。如果有平台能在我自己的任务上证明,长的规则文件和短的一样被遵守,我会重新考虑。

Try it on your own setup

No harness needed. Open your agent in your own repository and paste:

Audit the instruction files and skills in this repository. List: lines in the always-loaded file that you would get right without being told; rules written in more than one place; pairs of rules that contradict each other; rules that give no reason; and skills whose description is too vague to be found or too wide, with a better description for each. Mark the rules where a mistake would be costly and irreversible, since those need code and not text. Do not change any files.

在你自己的環境試試

不用裝 harness。在你自己的倉庫裡打開 agent,貼上:

審查這個倉庫裡的指令檔和 skill。列出:一直載入的檔案裡,不用說你也會做對的行;寫在不止一個地方的規則;互相矛盾的規則對;沒有給理由的規則;以及描述太含糊、找不到,或太寬的 skill,並為每一個給出更好的描述。標出犯錯會代價高昂又無法挽回的規則,那些需要程式碼,不是文字。不要改任何檔案。

在你自己的环境里试试

不用装 harness。在你自己的仓库里打开 agent,粘贴:

审查这个仓库里的指令文件和 skill。列出:始终加载的文件里,你不用交代也会做对的那些行;写在不止一个地方的规则;互相矛盾的规则对;没有写理由的规则;以及描述太含糊而找不到、或太宽泛的 skill,并为每个给出更好的描述。标出那些一旦出错代价高、又无法挽回的规则,因为它们需要代码,而不是文本。不要修改任何文件。

Go deeper

延伸閱讀

延伸阅读

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 uses all three places, the three levels of loading, and the rule that a rule has one source. The harness can show you each with the real files. After the setup above, type:

/harness-rookie-wondering I have read the chapter "Instructions and skills". Teach me how this harness uses the three places for rules, how its skills load in three levels, and why it says a skill is not enforced (topics 2, 3 and 15). Open the real files with me, starting from the shortest one.

It teaches one small piece at a time and opens the files with you.

在 harness 裡探索

Copilot Harness 用到了全部三個位置、三層載入,以及一條規則只有一個來源的做法。harness 可以用真實的檔案讓你看到每一樣。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「指令與 skill:只載入需要的」這一章。請教我這個 harness 怎麼用規則的三個位置、它的 skill 怎麼分三層載入,以及為什麼說 skill 不是強制執行的(主題 2、3 和 15)。帶我打開真實的檔案,從最短的那個開始。

它一次教一小塊,並和你一起打開檔案。

在 harness 里探索

Copilot Harness 用了这三个位置、三级加载,还有“一条规则只有一个来源”的原则。harness 能用真实的文件把每一样都展示给你。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“指令与 skill:只加载需要的”这一章。请教我这个 harness 是怎么用规则的三个位置的,它的 skill 是怎么分三级加载的,以及为什么它说 skill 不是强制执行的(主题 2、3 和 15)。带我打开真实的文件,从最短的那个开始。

它一次只教一小块,并和你一起打开文件。