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

2.4

Custom agentsCustom agent:固定模型和工具的角色自定义 agent:固定模型和工具的角色

This chapter assumes you have read Use subagents sparingly, or at least know what a subagent is.

讀這一章,請先讀過慎用子 agent,或至少知道子 agent 是什麼。

读这一章,需要你读过慎用子 agent,或者至少知道什么是子 agent。

The Knowledge經驗分享经验分享

In one sentence

Build a custom agent only when you must change the model or shrink the tools. To change what it knows or how it works, a skill or an instruction file is enough.

一句話

只有在必須換模型、或縮小工具時,才做 custom agent。要改它知道什麼、怎麼做事,用 skill 或指令檔就夠了。

一句话

只有在必须换模型、或者缩小工具范围时,才去建自定义 agent。要改的是它知道什么、怎么干活,一个 skill 或一个指令文件就够了。

For leaders

  • The decision: approve a custom agent only when it changes something that cannot be shared another way: its tools, its model, or a context that must not see the caller's reasoning.
  • The risk: a role that is only a different tone and some know-how is a costume: one more file to keep in step that the platform does not enforce. In my early setup, three job-title agents cost about 4.5 times the usage of one agent on four small tasks, run once each, with no better result.
  • The cost of doing it right: one agent file per real limit, changed through code review like any rule. Mine keeps only a read-only helper and a checker.
  • Ask the team: "Does this agent file list tools or a model? If not, why isn't it a skill?"

給主管

  • 要做的決定:只有 custom agent 改變了別的方式共用不了的東西時才批准:它的工具、它的模型,或一個不能看到呼叫者思路的上下文。
  • 風險:一個角色如果只是換了語氣、加了些做事的訣竅,它就只是一件戲服:多一個要同步維護的檔案,平台並不會強制執行它。在我早期的設定裡,三個按職位分工的 agent,在四個小任務上(每個只跑一次)用量約是一個 agent 的 4.5 倍,結果沒有更好。
  • 做對的成本:每一種真正的限制一個 agent 檔,像任何規則一樣走 code review 來改。我的只留了一個唯讀的幫手和一個檢查者。
  • 可以問團隊:「這個 agent 檔有列出工具或模型嗎?沒有的話,為什麼不是 skill?」

写给管理者

  • 要拍板的事:自定义 agent 只在它改变了别的办法共享不了的东西时才批:它的工具、它的模型,或者一份不能让它看到调用方推理过程的上下文。
  • 风险:一个只是换了语气、加了点专业知识的角色,是戏服:多一个要同步维护的文件,平台并不强制执行它。在我早期的配置里,三个按岗位分工的 agent,在四个小任务上(每个只跑了一次),用量约是一个 agent 的 4.5 倍,结果并没有更好。
  • 做对的代价:每一个真实的限制,对应一个 agent 文件,像任何规则一样通过代码审查来改。我的配置里只留了一个只读的帮手和一个检查者。
  • 可以问团队:“这个 agent 文件里列了工具或模型吗?如果没有,为什么它不是一个 skill?”

The problem

Use subagents sparingly asked whether to split work between agents. This chapter asks a smaller question: when you want a different agent, what do you actually have to build?

Many setups start by building roles: a "SQL expert", a "code reviewer", a "documentation writer", each as its own agent file. It feels like organizing. But look at what an agent file holds, and you find that most of it is something you could give to the default agent in another way. A role that is only a different tone and some know-how is a costume. It adds a thing to maintain and nothing the platform enforces.

Two words first.

  • A custom agent is a file that defines a role for the agent. In VS Code Copilot it is a file ending in .agent.md. It has a short header (name, description, settings) and a body of instructions.
  • The default agent is the plain agent you talk to when you pick nothing.

問題

慎用子 agent問的是要不要把工作分給多個 agent。這一章問一個小一點的問題:你想要另一個 agent 時,到底要做出什麼?

很多設定一開始就做角色:「SQL 專家」「程式碼 reviewer」「文件作者」,每個都是一個 agent 檔。這感覺像在整理。但看一看 agent 檔裡有什麼,你會發現大部分內容,用別的方式也能給預設 agent。一個角色如果只是換了語氣、加了些做事的訣竅,它就是一件戲服。它多了一個要維護的東西,卻沒有任何平台強制執行的東西。

先說兩個詞。

  • custom agent 是一個檔案,為 agent 定義一個角色。在 VS Code Copilot 裡,它是副檔名為 .agent.md 的檔案。它有一段簡短的檔頭(名稱、描述、設定)和一段指令正文。
  • 預設 agent 是你什麼都不選時對話的那個普通 agent。

问题

慎用子 agent问的是,要不要把工作分给多个 agent。这一章问的是一个更小的问题:你想要一个不一样的 agent 时,到底要搭什么?

很多配置一上来就搭角色:“SQL 专家”“代码 reviewer”“文档撰写者”,每个都是一个 agent 文件。这让人觉得井井有条。但看看 agent 文件里装的是什么,你会发现大部分内容,都可以用别的办法交给默认的 agent。一个只是换了语气、加了点专业知识的角色,就是戏服。它多出一样要维护的东西,却没有任何平台强制执行的内容。

先说两个词。

  • 自定义 agent 是为 agent 定义一个角色的文件。在 VS Code Copilot 里,它是以 .agent.md 结尾的文件。它有一小段头部(名字、描述、设置)和一段正文指令。
  • 默认 agent 是你什么都不选时,与你对话的那个普通 agent。

How it works

What is in an agent file

The header holds a few settings. These are the ones that matter, from the VS Code docs and from my own files:

  • A name and a description. The description tells the model when this agent is the right one to call. Write it for the caller: say what the agent is for and what it needs to be told. A subagent starts with an empty context (Use subagents sparingly), so a vague call message gives it nothing to work from.
  • A list of tools. If the file gives a list, only those tools are available to the agent.
  • A model, optional. It can be a list in order of preference: when the first cannot be used, the next one is tried.
  • Who may call it. Two settings, and they do different things. user-invocable: false keeps the agent out of the drop-down list (the VS Code docs call it picker visibility). A separate setting, disable-model-invocation, is for whether the model may call it as a subagent. See "Hidden is not forbidden" below.

The body is text: what the role is for, how it works, what it must not do, what it hands back.

What only an agent file can do

default agent custom agent which model your pick fixed in file which tools all of them only the list knowledge and habits same for both: instructions, skills Only the top two rows need a new agent.
A custom agent changes the model and the tools. What the agent knows and how it works can be given to any agent by instructions and skills.

Put the settings next to each other and ask: what can I give to the default agent some other way?

  • How it works, what it knows. Instruction files and skills reach any agent. A SQL style guide, a review checklist, the way things are named here: put them in a skill or an instruction file (Instructions and skills). The default agent then does the job, with no new agent.
  • Which tools it has. This cannot be given another way. An agent has the tools its file lists, and the platform enforces that list. An agent without the edit tools cannot edit, however it is asked. It is the hard limit an agent file gives you. (A rule written in the body of the file, "do not edit files", is a request like any other.)
  • Which model it uses. Also only an agent file. A cheap model for a simple job, or a strong one for hard thinking. The person can switch the model in the drop-down for the default agent, but a subagent's model is set in its file.
  • A separate context. When it runs as a subagent, it starts with an empty context, and only its report comes back. This is not a property of the file but of being a subagent. It is a reason to build one when you want an independent check, and Use subagents sparingly covers it.

So the rule I use is short. Build a custom agent when at least one of these cannot be shared: the tools differ, the model differs, or you need a context that must not see the caller's reasoning. For everything else, use the default agent and write the know-how down. A quick test: if you can say it as "when doing X, do it like this", it is a skill. If you can say it as "this job must not have tool Y" or "this job should run on model Z", it is an agent.

Before I add one, I ask two questions: which failure does it prevent, and why can the default agent not do the same?

The VS Code context engineering guide offers agents for "workflows that follow a multi-turn process with specific tools", and its example planning agent has a short, read-only tool list and an instruction not to implement. That is the same shape: the tool list is the limit, the instruction is a request.

An example: the reviewer

In my setup there is one custom agent I would keep above all others: the reviewer. It is a checker that sees only the request and the result. Here is the top of its file:

The header of the reviewer: the tools line is the limit, the model line is a fallback list, the description is a request to the model that calls it.
---
name: reviewer
description: The independent checker. The default agent calls it when the user switches checks on ([review]=n). It looks only at the requirement, the work and the diff, gives PASS or FAIL, and names file:line for every finding. It changes no file.
user-invocable: false
agents: []
model: ['Claude Sonnet 5.5 (copilot)', 'Claude Sonnet 5.5', 'Claude Haiku 5.5 (copilot)', 'Claude Haiku 5.5', 'Claude Haiku 4.5 (copilot)', 'Claude Haiku 4.5']
tools: ['read', 'search', 'execute']
---

The tools line gives it tools for reading, searching and running commands, and none for changing files. So it cannot "just fix it". agents: [] means it cannot start other subagents. The model is a fallback list, so if the first model cannot be used, the next one is. The reasons for each choice are in Use subagents sparingly. What matters here: every line of the header that changes behavior is a tool limit, a model, or a boundary of context. The description only asks. The body mostly says what to look at and what to hand back.

Three facts that bit me

"Hidden" is not "forbidden". A setting that keeps an agent out of the drop-down list does not stop another agent from calling it as a subagent. Neither does the setting that keeps the model from using it. If "who may call whom" matters, a hook has to decide it (Hooks), not these two settings.

A hook cannot see which agent is current. The events a hook receives carry no name for the main agent (Hooks), so rights cannot be handed to "the admin agent": any agent could pass for it. Rights have to follow the session instead, as in my setup, where an admin switch is turned on by the person in a terminal (Guard the files that hold the rules). I once had an admin agent and retired it.

A model above the caller may be silently skipped. I saw this once and have not tested it again: when a subagent's model is a class above the main model, the platform does not run it and says nothing. So "did the check really happen" has to be confirmed by something that is not the model, such as a hook that saves the reviewer's answer to disk. If a check matters to you, keep a record that it ran.

Test your own setup

Take one role agent you have (a "SQL expert", a "documentation writer"). Does its file list tools, or a model? If neither, move its body into a skill (Instructions and skills), give the same task to the default agent with and without the skill, and compare. If you see no difference, the agent was a costume. Run each a few times before you trust what you see.

原理

agent 檔裡有什麼

檔頭放幾個設定。以下是重要的幾個,來自 VS Code 文件和我自己的檔案:

  • 名稱和描述。描述告訴模型什麼時候該呼叫這個 agent。要為呼叫者寫:說明這個 agent 是做什麼的、需要被告知什麼。子 agent 從空的上下文開始(慎用子 agent),所以含糊的呼叫訊息讓它無從下手。
  • 工具清單。檔案裡給了清單,這個 agent 就只能用清單裡的工具。
  • 模型,可選。可以是一個依偏好排序的清單:第一個用不了,就試下一個。
  • 誰可以呼叫它。有兩個設定,作用不同。user-invocable: false 讓這個 agent 不出現在下拉清單裡(VS Code 文件稱之為 picker visibility)。另一個設定 disable-model-invocation 管的是模型能不能把它當子 agent 呼叫。見下面的「隱藏不等於禁止」。

正文是文字:這個角色做什麼、怎麼做、不能做什麼、交回什麼。

只有 agent 檔能做的事

預設 agent custom agent 用哪個模型 你選的那個 寫死在檔案裡 有哪些工具 全部 只有清單上的 知道什麼、怎麼做事 兩邊一樣:instructions 和 skill 對誰都有效 只有上面兩列,才需要新建一個 agent。
custom agent 改的是模型和工具。agent 知道什麼、怎麼做事,用 instructions 和 skill 就能交給任何 agent。

把這些設定放在一起,問一句:哪些我可以用別的方式交給預設 agent?

  • 怎麼做事、知道什麼。指令檔和 skill 對任何 agent 都有效。SQL 風格指南、review 清單、這裡的命名習慣:放進 skill 或指令檔(指令與 skill:只載入需要的)。這樣預設 agent 就能做這份工作,不用新的 agent。
  • 有哪些工具。這沒有別的方式可以給。一個 agent 有它的檔案列出的工具,平台會強制執行這份清單。沒有編輯工具的 agent,怎麼要求都改不了檔案。這是 agent 檔能給你的硬限制。(寫在檔案正文裡的規則,「不要編輯檔案」,和別的規則一樣只是請求。)
  • 用哪個模型。這也只有 agent 檔能做。簡單的工作用便宜的模型,難的思考用強的。使用者可以在下拉清單裡為預設 agent 切換模型,但子 agent 的模型是在它的檔案裡設定的。
  • 獨立的上下文。作為子 agent 執行時,它從空的上下文開始,只有它的報告會交回來。這不是檔案的性質,而是子 agent 的性質。想要獨立檢查時,這就是做一個的理由,慎用子 agent講過。

所以我用的規則很短。至少有一樣共用不了時,才做 custom agent:工具不同、模型不同,或需要一個不能看到呼叫者思路的上下文。其他情況,用預設 agent,把做事的訣竅寫下來。一個快速的判斷:如果你能把它說成「做 X 的時候,這樣做」,它就是 skill。如果你能說成「這份工作不能有工具 Y」或「這份工作要用模型 Z」,它就是 agent。

加一個之前,我問兩個問題:它防的是哪種失敗?預設 agent 為什麼做不到同樣的事?

VS Code 的上下文工程指南建議,「按多輪流程、用特定工具來走的 workflow」可以用 agent,它的範例規劃 agent 有一份簡短的唯讀工具清單,和一句不要動手實作的指令。形狀是一樣的:工具清單是限制,指令是請求。

一個例子:reviewer

在我的設定裡,有一個 custom agent 我最想留:reviewer。它是一個只看需求和結果的檢查者。下面是它檔案的開頭:

reviewer 的檔頭:tools 那一行是限制,model 那一行是備用清單,描述是對呼叫它的模型的請求。
---
name: reviewer
description: The independent checker. The default agent calls it when the user switches checks on ([review]=n). It looks only at the requirement, the work and the diff, gives PASS or FAIL, and names file:line for every finding. It changes no file.
user-invocable: false
agents: []
model: ['Claude Sonnet 5.5 (copilot)', 'Claude Sonnet 5.5', 'Claude Haiku 5.5 (copilot)', 'Claude Haiku 5.5', 'Claude Haiku 4.5 (copilot)', 'Claude Haiku 4.5']
tools: ['read', 'search', 'execute']
---

tools 那一行給了它讀取、搜尋和執行指令的工具,沒有改檔案的工具。所以它不能「順手修掉」。agents: [] 表示它不能再開別的子 agent。模型是一份備用清單,第一個用不了,就用下一個。每個選擇的理由在慎用子 agent。這裡要看的是:檔頭裡每一行會改變行為的,不是工具限制,就是模型,或是上下文的邊界。描述只是請求。正文大多是在說看什麼、交回什麼。

三件讓我吃過虧的事

「隱藏」不等於「禁止」。讓 agent 不出現在下拉清單的設定,擋不住另一個 agent 把它當子 agent 呼叫。不讓模型使用它的那個設定也一樣。「誰可以呼叫誰」如果重要,要由 hook 來決定(Hooks:每次呼叫都會經過的執行點),不是這兩個設定。

hook 看不到目前是哪個 agent。hook 收到的事件裡,沒有主 agent 的名字(Hooks:每次呼叫都會經過的執行點),所以不能把權限交給「admin agent」:任何 agent 都能冒充它。權限只能跟著會話走,就像我的設定:admin 開關由使用者在終端機裡打開(保護規則本身的檔案)。我曾經有過一個 admin agent,後來撤掉了。

比呼叫者高一級的模型,可能被悄悄跳過。我見過一次,沒有再測:子 agent 的模型比主模型高一個等級時,平台不執行它,也不說一聲。所以「檢查到底有沒有做」,要由不是模型的東西來確認,例如一個把 reviewer 的回答存到磁碟的 hook。檢查如果對你重要,就留一份它執行過的紀錄。

測一測你自己的設定

拿一個你有的角色 agent(「SQL 專家」「文件作者」)。它的檔案有列出工具或模型嗎?都沒有的話,把它的正文搬進 skill(指令與 skill:只載入需要的),同一個任務給預設 agent,分別在有 skill 和沒有 skill 時做,然後比較。看不出差別,這個 agent 就是戲服。每種多跑幾次,再相信你看到的。

原理

agent 文件里有什么

头部有几项设置。下面这些是要紧的,来自 VS Code 的文档和我自己的文件:

  • 名字和描述。描述告诉模型什么时候该调用这个 agent。要写给调用方看:说明这个 agent 是做什么的,需要被告知什么。子 agent 从空白的上下文开始(慎用子 agent),所以含糊的调用消息,让它无从下手。
  • 工具清单。文件里给了清单,这个 agent 就只有清单上的工具。
  • 模型,可选。它可以是一份按偏好排序的列表:第一个用不了,就试下一个。
  • 谁可以调用它。有两个设置,作用不同。user-invocable: false 让这个 agent 不出现在下拉列表里(VS Code 文档叫它选择器里的可见性)。另一个单独的设置 disable-model-invocation,管的是模型能不能把它当子 agent 调用。见下面的“隐藏不等于禁止”。

正文是文本:这个角色是干什么的、怎么干、不能做什么、交回什么。

只有 agent 文件才能做到的

默认 agent 自定义 agent 用哪个模型 你选的那个 写死在文件里 有哪些工具 全部 只有清单上的 知道什么、怎么干活 两边一样:指令和 skill 只有上面两行,才需要新建一个 agent。
自定义 agent 改的是模型和工具。agent 知道什么、怎么干活,用指令和 skill 就能交给任何 agent。

把这些设置并排放在一起,然后问:哪些东西,我可以用别的办法交给默认 agent?

  • 怎么干活、知道什么。指令文件和 skill 对任何 agent 都有效。SQL 风格指南、检查清单、这里的命名方式:放进 skill 或指令文件(指令与 skill:只加载需要的)。这样默认 agent 就能干这份活,不需要新的 agent。
  • 有哪些工具。这没法用别的办法给。一个 agent 有它的文件里列出的那些工具,平台会强制执行这份清单。没有编辑工具的 agent,无论你怎么要求,都编辑不了。这是 agent 文件能给你的硬性限制。(写在文件正文里的规则,比如“不要改文件”,和别的规则一样是请求。)
  • 用哪个模型。同样只有 agent 文件能做到。简单的活用便宜的模型,难的思考用强的。人可以在下拉列表里切换默认 agent 的模型,但子 agent 的模型是在它的文件里设的。
  • 独立的上下文。作为子 agent 运行时,它从空白的上下文开始,只有它的报告会回来。这不是文件的属性,而是子 agent 这个身份的属性。想要独立检查时,这是搭一个的理由,慎用子 agent讲了这一点。

所以我用的规则很短。这几样里至少有一样没法共享时,才建自定义 agent:工具不同、模型不同,或者你需要一份不能让它看到调用方推理过程的上下文。 其他情况,都用默认 agent,把专业知识写下来。一个快速的检验:如果你能把它说成“做 X 的时候,这样做”,它就是 skill。如果你能把它说成“这份活不能有工具 Y”或者“这份活要用模型 Z 来跑”,它就是 agent。

加一个之前,我问两个问题:它防的是哪种故障?默认 agent 为什么做不到同样的事?

VS Code 的上下文工程指南把 agent 用在“遵循多轮流程、使用特定工具的 workflow”上,它的示例规划 agent 有一份简短的只读工具清单,和一条不要去实现的指令。这是同样的形状:工具清单是限制,指令是请求。

一个例子:reviewer

在我的配置里,有一个自定义 agent,是我比其他所有都更想保留的:reviewer。它是一个检查者,只看需求和结果。下面是它文件的开头:

reviewer 的头部:tools 那一行是限制,model 那一行是备选列表,description 是对调用它的模型的请求。
---
name: reviewer
description: The independent checker. The default agent calls it when the user switches checks on ([review]=n). It looks only at the requirement, the work and the diff, gives PASS or FAIL, and names file:line for every finding. It changes no file.
user-invocable: false
agents: []
model: ['Claude Sonnet 5.5 (copilot)', 'Claude Sonnet 5.5', 'Claude Haiku 5.5 (copilot)', 'Claude Haiku 5.5', 'Claude Haiku 4.5 (copilot)', 'Claude Haiku 4.5']
tools: ['read', 'search', 'execute']
---

tools 那一行给了它读、搜索和运行命令的工具,没有改文件的。所以它没法“顺手修一下”。agents: [] 表示它不能再启动别的子 agent。模型是一份备选列表,第一个用不了,就用下一个。每一项选择的理由,在慎用子 agent里。这里要紧的是:头部里每一行会改变行为的,要么是工具限制,要么是模型,要么是上下文的边界。描述只是在请求。正文主要说该看什么、该交回什么。

我踩过的三个坑

“隐藏”不等于“禁止”。让一个 agent 不出现在下拉列表里的设置,拦不住另一个 agent 把它当子 agent 来调用。让模型不去使用它的那个设置,也拦不住。如果“谁可以调用谁”很要紧,要由 hook 来决定(Hook:每次调用都会经过的执行点),不能靠这两个设置。

hook 看不到当前是哪个 agent。hook 收到的事件里,没有主 agent 的名字(Hook:每次调用都会经过的执行点),所以不能把权限交给“admin agent”:任何 agent 都可以冒充它。权限只能跟着会话走,比如在我的配置里,admin 开关是由人在终端里打开的(保护规则本身的文件)。我曾经有过一个 admin agent,后来撤掉了。

比调用方更高一级的模型,可能被悄悄跳过。这个我见过一次,之后没再测过:当子 agent 的模型比主模型高一个级别时,平台不会运行它,也不吭声。所以“检查到底有没有发生”,必须由模型之外的东西来确认,比如一个把 reviewer 的回答存到磁盘上的 hook。一道检查如果对你要紧,就留一份它运行过的记录。

测一测你自己的配置

拿你有的一个角色 agent(“SQL 专家”“文档撰写者”)。它的文件里列了工具或模型吗?都没有的话,把它的正文挪进一个 skill(指令与 skill:只加载需要的),把同一个任务交给默认 agent,一次带这个 skill,一次不带,对比一下。如果看不出差别,这个 agent 就是戏服。每种多跑几次,再相信你看到的。

Costs and traps

More agents are more to keep in step. Each file has a model name, a tool list and a body that can go out of date. Model names change. A name that no longer matches the drop-down breaks the agent. An agent file sets limits, so in a team change it through code review like any rule.

A switch may lose the chat. The VS Code docs say a selected agent applies to your requests until you switch. They do not say what happens to the chat history on a plain switch, and I have not tested it. Keep what matters in files (Long chats get worse).

A role can feel like a limit when it is only a request. The body says "do not do X" and the agent does X anyway. Only the tool list is a limit.

Fewer roles than you think. In my early setup I had three job-title agents (one to coordinate, one to build, one to check). On four small tasks they cost about 4.5 times the usage of one agent and gave no better result (Use subagents sparingly). I kept only the checker. That is four tasks, once each: weak evidence, not a result. Anthropic reports the same direction on a different scale: in their research system, agents use about 4 times the tokens of a chat, and multi-agent systems about 15 times (How we built our multi-agent research system). My number and theirs measure different things, so compare only the direction.

代價和陷阱

agent 越多,要同步維護的越多。每個檔案都有模型名稱、工具清單和一段會過期的正文。模型名稱會變。名稱和下拉清單對不上,這個 agent 就壞了。agent 檔設定的是限制,所以在團隊裡,要像任何規則一樣走 code review 來改。

切換可能會丟掉對話。VS Code 文件說,選定的 agent 會一直用在你的請求上,直到你切換。切換時對話紀錄會怎樣,文件沒說,我也沒測過。要緊的東西存進檔案(長對話會變差)。

角色可能感覺像限制,其實只是請求。正文寫著「不要做 X」,agent 還是做了 X。只有工具清單是限制。

角色比你想的要少。在我早期的設定裡,有三個按職位分工的 agent(一個協調、一個實作、一個檢查)。在四個小任務上,它們的用量約是一個 agent 的 4.5 倍,結果沒有更好(慎用子 agent)。我只留了檢查者。這是四個任務、各跑一次:證據很弱,不是結論。Anthropic 在不同的規模上報告了同樣的方向:在他們的研究系統裡,agent 用的 token 約是聊天的 4 倍,多 agent 系統約是 15 倍(How we built our multi-agent research system)。我的數字和他們的量的是不同的東西,所以只比較方向。

代价和坑

agent 越多,要同步维护的越多。每个文件里都有模型名、工具清单和一段会过期的正文。模型名会变。和下拉列表对不上的名字,会让 agent 坏掉。agent 文件设定的是限制,所以在团队里,像任何规则一样通过代码审查来改。

切换可能丢掉对话。VS Code 文档说,选定的 agent 会作用于你的请求,直到你切换。对于一次单纯的切换,对话历史会怎么样,文档没有说,我也没测过。要紧的东西放在文件里(长对话会变差)。

角色可能让人觉得是限制,其实只是请求。正文写着“不要做 X”,agent 照样做了 X。只有工具清单才是限制。

角色比你以为的要少。在我早期的配置里,我有三个按岗位分工的 agent(一个协调、一个开发、一个检查)。在四个小任务上,它们的用量约是一个 agent 的 4.5 倍,结果并没有更好(慎用子 agent)。我只留下了检查者。那是四个任务、每个一次:是薄弱的证据,不是结果。Anthropic 在另一个量级上报告了同样的方向:在他们的研究系统里,agent 用的 token 约是聊天的 4 倍,多 agent 系统约是 15 倍(How we built our multi-agent research system)。我的数字和他们的,衡量的是不同的东西,所以只比较方向。

When to delete it Industry practice

An agent file stays as long as it enforces something a skill cannot: a tool list or a model. Some platforms already let a skill carry tool settings. In Claude Code, a skill's allowed-tools only pre-approves tools and does not restrict them, and a separate disallowed-tools removes tools while the skill is active (Skills). Whether such a setting is enforced on your platform is something to check. Where it is, many agent files become unnecessary. And any agent whose only content is "act like an expert in X" can be deleted today.

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

只要 agent 檔強制執行了 skill 做不到的東西:工具清單或模型,它就該留著。有些平台已經讓 skill 帶工具設定。在 Claude Code 裡,skill 的 allowed-tools 只是預先批准工具,並不限制工具;另有一個 disallowed-tools,在 skill 啟用期間移除工具(Skills)。這樣的設定在你的平台上有沒有強制執行,要自己去查。有的話,很多 agent 檔就不需要了。而任何內容只有「表現得像 X 的專家」的 agent,今天就可以刪掉。

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

只要 agent 文件强制执行了 skill 做不到的东西:工具清单或模型,它就留着。有些平台已经让 skill 带上工具设置。在 Claude Code 里,skill 的 allowed-tools 只是预先批准某些工具,并不限制,而另一个单独的 disallowed-tools,会在 skill 生效期间移除工具(Skills)。这样的设置在你的平台上是不是强制执行的,要自己去查。如果是,很多 agent 文件就不再需要了。而任何内容只是“表现得像 X 领域专家”的 agent,今天就可以删。

Try it on your own setup

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

Find every custom agent file in this project. For each one, report: does its header limit the tools, set a model, or neither; is the description written so a caller knows when to use it and what to say; and which lines of the body are only requests. Mark every agent with no tool limit and no model setting as a likely costume, and say which skill or instruction file could replace it. Do not change any files.

在你自己的環境試試

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

找出這個專案裡所有的 custom agent 檔。每一個回報:檔頭有沒有限制工具、設定模型,還是兩者都沒有;描述的寫法,是否讓呼叫者知道什麼時候用它、要說什麼;正文的哪幾行只是請求。沒有工具限制、也沒有模型設定的 agent,標成可能是戲服,並說明哪個 skill 或指令檔可以取代它。不要改任何檔案。

在你自己的环境里试试

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

找出这个项目里每一个自定义 agent 文件。每一个,报告:它的头部是限制了工具、设置了模型,还是都没有;描述写得是否让调用方知道什么时候该用、该说什么;以及正文里哪些行只是请求。把没有工具限制、也没有模型设置的 agent,都标为疑似戏服,并说明哪个 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

The harness has a very small set of custom agents on purpose: a read-only helper and a checker. You can open both files and compare each line with the table above. After the setup above, type:

/harness-rookie-wondering I have read the chapter "Custom agents". Teach me what is in this harness's agent files: the tool lists, the model lists, and which lines change behavior and which are only requests. Open the real files with me, and show me why there are so few agents.

It teaches one small piece at a time, stops to ask if you are following, and opens the files with you.

在 harness 裡探索

harness 裡刻意只放了很少的 custom agent:一個唯讀的幫手和一個檢查者。你可以打開這兩個檔案,把每一行和上面的表對照。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「Custom agent:固定模型和工具的角色」這一章。請教我這個 harness 的 agent 檔裡有什麼:工具清單、模型清單,哪幾行會改變行為、哪幾行只是請求。每一項都帶我打開真實的檔案,並告訴我為什麼 agent 這麼少。

它一次教一小塊,停下來確認你跟得上,然後和你一起打開檔案。

在 harness 里探索

harness 里的自定义 agent 特意只有很小的一组:一个只读的帮手和一个检查者。你可以打开这两个文件,把每一行和上面的表对照。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“自定义 agent”这一章。请教我这个 harness 的 agent 文件里有什么:工具清单、模型列表,以及哪些行会改变行为、哪些只是请求。带我打开真实的文件,并让我看看为什么 agent 这么少。

它一次只教一小块,停下来确认你跟上了,再和你一起打开文件。