maintain-environment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maintain the environment

维护环境

The environment is what agents run with: permissions, global instructions, project instructions, and skills. Use this skill to change it; to set up a machine or a project, use

/set-up-machine

/set-up-project

instead. Write each change once, at its source, and carry it from there to every harness, machine and install it applies to. Keep harness memory features off, because a memory is invisible to every other harness and lives outside any repository; write what it would hold into one of the layers instead. The skills repo and most projects are public, so write personal detail only in the user's workstation repo, or the shared global instructions file on a machine without one: names, accounts, paths on the user's machine, other projects. In a skill or a public

AGENTS.md

, generalise it or make it a parameter.

环境是 Agent 运行所依赖的一切：权限、全局指令、项目指令和 skill。使用此 skill 来修改环境；若要设置机器或项目，请改用

/set-up-machine

或

/set-up-project

。每项变更都应只在其源头编写一次，并从源头传播到其适用的每个 harness、机器和安装实例。关闭 harness 的 memory 功能，因为 memory 对其他 harness 不可见，并且位于任何 repository 之外；应将原本由它保存的内容写入上述某一层。skills repo 和大多数项目都是公开的，因此个人详细信息只能写入用户的 workstation repo；如果机器上没有 workstation repo，则写入该机器上的共享全局指令文件，包括姓名、账号、用户机器上的路径、其他项目的信息等。对于 skill 或公开的

AGENTS.md

，应将此类信息泛化或设为参数。

Parameters

参数

```
<skills-repo>
```
: the user's own skills repo on GitHub, as
```
owner/repo
```
.
```
<path-to-skills-repo>
```
: where that repo is cloned.

```
<skills-repo>
```
：用户在 GitHub 上的自有 skills repo，以
```
owner/repo
```
表示。
```
<path-to-skills-repo>
```
：该 repo 的 clone 所在位置。

Environment layers

环境层级

Write each instruction, rule or piece of know-how in one place only, so changing it later is a one-place edit. Two questions choose the place. Who needs it: only this user, anyone working on one project, or any agent doing a task? And must it be enforced, or is it guidance? The table runs from enforced to guidance; go down it and use the first row that fits. Elsewhere, point at it only where a reader wouldn't otherwise find it.

Layer	Holds	Where to write it
Permission	A hard rule: deny, ask, allow-and-report or, for a personal permission only, allow.	A rule for anybody is a row in `/set-up-machine` 's rule table, which `/set-up-machine` turns into each harness's native entries and the hook uses for rejection guidance. A personal permission, such as allowing a tool the user added, goes in the user's workstation repo. A project may only add allows.
Global instruction	The user's personal workflow and environment defaults, concise permission-rejection guidance and a secrets guardrail.	The user's workstation repo, from which `/set-up-machine` writes the shared global instructions file every harness on the machine reads. The compact rules block comes from `/set-up-machine` 's `references/global-instructions.md` .
Project `AGENTS.md`	Anything a teammate needs to work on the project: its tracker, its commands, its conventions, its worktree tool.	The project's `AGENTS.md` , with a `CLAUDE.md` holding `@AGENTS.md` so Claude Code reads the same text.
Skill	How to do a task, written for any team's tools and tracker: a value that differs between setups becomes a parameter.	A `SKILL.md` in the skills repo, or a local skill in one project.
Skill reference	Detail only some runs need, such as one branch of the flow or one tool's specifics; anything every run needs stays in `SKILL.md` .	A file beside the `SKILL.md` . The skill's body says when to read it, and its closing `## References` section says in one line what each file covers; scripts get a `## Scripts` section the same way.

每条指令、规则或专业知识都只写在一个位置，这样以后修改时只需编辑一处。通过两个问题决定放置位置：谁需要它——仅该用户、参与某一个项目的任何人，还是执行任务的任何 Agent？它必须被强制执行，还是仅作为指导？表格按从强制执行到指导排列；逐行向下查看，并使用第一个适合的行。在其他位置，仅当读者无法自行找到时才指向它。

层级	存放内容	写入位置
Permission	硬性规则：拒绝、询问、允许并报告；对于仅限个人的权限，还可设为允许。	适用于任何人的规则是 `/set-up-machine` 的 rule table 中的一行； `/set-up-machine` 会把它转换为每个 harness 的原生配置项，hook 会使用这些配置项提供拒绝指导。个人权限（例如允许用户新增的工具）应写入用户的 workstation repo。项目只能添加允许项。
Global instruction	用户的个人工作流和 environment defaults、权限被拒时的简短指导，以及 secrets 防护规则。	用户的 workstation repo； `/set-up-machine` 会从该处写出共享全局指令文件，机器上的每个 harness 都会读取该文件。精简规则块来自 `/set-up-machine` 的 `references/global-instructions.md` 。
Project `AGENTS.md`	团队成员为项目工作所需的一切：其 tracker、命令、约定和 worktree 工具。	项目的 `AGENTS.md` ；另在 `CLAUDE.md` 中保存 @AGENTS.md，让 Claude Code 读取相同文本。
Skill	如何完成某项任务，为任何团队的工具和 tracker 编写；不同环境之间存在差异的值应设为参数。	skills repo 中的 `SKILL.md` ，或某个项目中的 local skill。
Skill reference	仅部分运行才需要的细节，例如流程的某个分支或某个工具的特定信息；每次运行都需要的内容应保留在 `SKILL.md` 中。	`SKILL.md` 旁的文件。skill 正文应说明何时读取该文件，结尾的 `## References` 部分应各用一行说明每个文件涵盖的内容；脚本同样应设置 `## Scripts` 部分。

The "team test"

团队测试（team test）

Before settling a change, picture a teammate or contributor with a different setup: another harness, a different session host, and a machine set up with

/set-up-machine

but none of the user's personal workflow. After the change they must still be able to work on any of the user's projects using only that project's instructions, the skills and the roles

/set-up-machine

writes.

A change passes when:

nothing a teammate needs sits in the global instructions;
the global instructions hold only the user's personal workflow, their environment defaults, permission-rejection guidance and a secrets guardrail;
no skill depends on the user's default tool. The user's choice of tool sits in their environment defaults, and how to use a tool sits in that tool's own skill.

Flag every place a change fails the test, and move the failing part to the row of the table that fits it.

The test also decides between the skills repo and the workstation repo. What anybody could use, such as a safety rule or how to do a task, goes in a skill or the rule table. What holds only for this user, such as which tool fills a role, a personal workflow line or a personal permission, goes in their workstation repo.

在确定变更前，设想像一位配置不同的团队成员或贡献者：另一个 harness、不同的 session host，以及一台通过

/set-up-machine

设置、但没有用户个人工作流的机器。变更后，他们仍必须能够仅使用该项目的指令、skills 以及

/set-up-machine

写入的角色，在用户的任何项目上工作。

一项变更通过测试的条件是：

没有任何团队成员需要的内容放在 global instructions 中；
global instructions 只保存用户的个人工作流、environment defaults、权限拒绝指导和 secrets 防护规则；
没有 skill 依赖用户的默认工具。用户选择的工具存放在其 environment defaults 中，而工具的使用方式存放在该工具自身的 skill 中。

标出变更未通过测试的每一处，并将失败的部分移到表格中与其匹配的行。

测试也决定了应使用 skills repo 还是 workstation repo。任何人都可以使用的内容（例如安全规则或完成某项任务的方法）放入 skill 或 rule table。仅对该用户有效的内容（例如由哪个工具承担某个角色、一行个人工作流或个人权限）放入 workstation repo。

Skill parameters

Skill 参数

A skill that needs a value from the environment (a tool, a command, a repo) declares it as a parameter:

One
## Parameters
section, in
SKILL.md
, added only to a skill that needs such a value, with one short line per parameter: the
```
<kebab-case>
```
placeholder named after its role, what it is, and a few examples after "e.g.". For instance: "
```
<session-host>
```
: where agent sessions run, e.g.
```
herdr
```
, Claude Code Desktop, Codex Desktop."
Write what to do when a role has no tool once, in
```
/set-up-machine
```
's roles table, which
```
/set-up-machine
```
copies into the environment defaults on every machine. Never repeat it in a skill, since a copy drifts from the table.
Say when to use a tool in the tool's own skill, in its description ("Use when the project's worktree tool is
```
treehouse
```
"), along with anything specific to that tool. No other skill routes to it.
In the body, use the placeholder as a noun ("make the worktree with
```
<worktree-tool>
```
"). Anywhere else, use plain words ("the session host").
Name another skill by its slash command, such as
```
/to-tickets
```
, not in bold. A starting prompt is the exception: it names skills in words, so it works in every harness.

Before any skill uses a new role, add it to

/set-up-machine

's roles table, with what it is and what to do when it has no tool.

需要从环境中获取值（工具、命令、repo）的 skill 应将其声明为 parameter：

仅在需要此类值的 skill 中，于
SKILL.md
里添加一个
## Parameters
部分，每个 parameter 用一行简要说明：以角色命名的
```
<kebab-case>
```
placeholder、它是什么，以及在 “e.g.” 后给出几个示例。例如：“
```
<session-host>
```
：Agent session 的运行位置，例如
```
herdr
```
、Claude Code Desktop、Codex Desktop。”
一个角色没有可用工具时的处理方式只写一次， 写在
```
/set-up-machine
```
的 roles table 中；
```
/set-up-machine
```
会把它复制到每台机器的 environment defaults 中。绝不要在 skill 中重复，因为副本会与表格失去同步。
在工具自身的 skill 中说明何时使用该工具， 写入该 skill 的 description（“当项目的 worktree 工具是
```
treehouse
```
时使用”），并附上该工具特有的信息。不要让其他 skill 路由到它。
在正文中，将 placeholder 用作名词（“使用
```
<worktree-tool>
```
创建 worktree”）。其他位置则使用普通词语（“session host”）。
通过斜杠命令引用另一个 skill， 例如
```
/to-tickets
```
，不要加粗。启动 prompt 是例外：它应以文字提及 skill，以便在每个 harness 中都能使用。

在新 skill 使用新角色之前，先把它加入

/set-up-machine

的 roles table，并说明它是什么以及没有工具可用时该怎么做。

Steps

步骤

Choose the layer the change belongs to, and check it against the team test.
Make the change at that layer's source. For any operation on a skill, read
```
skill-operations.md
```
.
- For an installed skill: that is its source repo, never an installed copy, which the next
```
npx skills update
```
  overwrites.
- For a local skill: that is the project.
- For a personal change (a personal preference, an environment default or a personal permission): that is the workstation repo the pointer
```
~/.config/agents/source.md
```
  names, in its clone.
```
/set-up-machine
```
  's
```
references/workstation-repo.md
```
  says which file each kind goes in. Leave the shared file's generated parts and the harness settings to
```
/set-up-machine
```
  , since its next run rewrites them from the repository.
- When the pointer is missing: set one up through
```
/set-up-machine
```
  first, then make the change in the repository it names.
- When the pointer records no workstation repo: write a personal instruction in the shared file itself, which is its source on such a machine. A personal permission has no home there, so offer to set up a workstation repo through
```
/set-up-machine
```
  .
After any skill change, run the team-test audit: grep the skills for the name of each tool in the user's environment defaults, and for "environment defaults". Skip each tool's own skill, and
```
/set-up-machine
```
,
```
/set-up-project
```
and this skill, which manage the instruction files. Judge each hit:
- When it is a default, the skill picks the tool itself: make it a parameter, and move the tool's commands into the tool's own skill.
- When it is a mention, an example such as a parameter's "e.g.", or data: keep it.
- When it names the environment defaults: remove the mention. An agent that has them loaded already sees them, and one that doesn't is pointed at nothing.
Ship a change to the skills repo on a branch, through a pull request opened with
```
/to-pr
```
, and stop once it is open. The user merges it or asks you to.
Carry the change everywhere it applies, as the table below says.
```
npx skills
```
installs from the default branch, so the installs and updates run after the merge, in the session told the pull request merged.
Report each step this session can't carry: which set-up skill or
```
npx skills update
```
still has to run, and whether it runs on this machine, on each other machine or in each project.

Change	How it reaches everywhere
A permission for anybody	Ship the `/set-up-machine` rule-table row; after the merge, update the installed skills and rerun `/set-up-machine` on each machine.
A personal change	Have the user commit and push it in their workstation repo, then pull it into the clone and rerun `/set-up-machine` on each machine.
A global instruction with no workstation repo	Rerun `/set-up-machine` on each machine; every harness reads the one shared file.
A project instruction or project permission	Commit it in the project. For a standard every project shares, change `/set-up-project` instead and rerun it in each project.
A skill in a source repo	Ship it; after the merge, `npx skills update <name>` in every scope that installs it, on every machine. A machine whose workstation repo lists the skill in `agents/installs.json` also gets the update from a `/set-up-machine` run.
A local skill	Commit it with the project.
A set-up skill itself	Treat it as a skill change first, then rerun that set-up skill wherever it applies.

When the user asks what a skill costs to run, or how to make it cheaper, follow

efficiency-analysis.md

选择变更所属的层级，并对照 team test 检查。
在该层级的源头进行变更。对 skill 执行任何操作前，阅读
```
skill-operations.md
```
。
- 对于已安装的 skill： 源头是它的 source repo，绝不能直接修改 installed copy，因为下一次
```
npx skills update
```
  会覆盖该副本。
- 对于 local skill： 源头就是项目。
- 对于个人变更（个人偏好、environment default 或个人权限）：源头是指针
```
~/.config/agents/source.md
```
  所指向的 workstation repo 及其 clone。
```
/set-up-machine
```
  的
```
references/workstation-repo.md
```
  会指明各类变更应写入哪个文件。共享文件中的生成部分和 harness settings 应留给
```
/set-up-machine
```
  处理，因为其下次运行会根据 repo 重写这些内容。
- 当指针不存在时： 先通过
```
/set-up-machine
```
  设置一个，然后在它所指向的 repo 中进行变更。
- 当指针未记录 workstation repo 时： 在共享文件本身写入一条个人指令；在这种机器上，该文件就是源头。个人权限在那里没有存放位置，因此应主动提出通过
```
/set-up-machine
```
  设置 workstation repo。
任何 skill 变更后，运行 team-test audit：在 skills 中 grep 用户 environment defaults 中每个工具的名称，以及 “environment defaults”。跳过每个工具自身的 skill，以及
```
/set-up-machine
```
、
```
/set-up-project
```
和此 skill，因为它们负责管理指令文件。逐一判断每个匹配项：
- 当匹配项是 default 工具时， 该 skill 会自行选择工具：把它改成 parameter，并将工具命令移入该工具自身的 skill。
- 当它只是一处 mention 时， 例如 parameter 的 “e.g.” 或数据：予以保留。
- 当它提到 environment defaults 时： 删除这处提及。已加载这些默认值的 Agent 本就能看到它们，而未加载的 Agent 则无从找到任何指引。
在分支上将变更交付到 skills repo，通过使用
```
/to-pr
```
打开的 pull request 提交，并在 pull request 打开后停止。由用户自行合并，或按用户要求执行合并。
按下表将变更传播到所有适用位置。
```
npx skills
```
从默认分支安装，因此安装和更新应在合并后、于收到 pull request 已合并通知的 session 中运行。
报告本次 session 无法完成的每个步骤：仍需运行哪个 set-up skill 或
```
npx skills update
```
，以及它需要在本机、其他每台机器还是每个项目中运行。

变更	如何传播到所有位置
适用于任何人的权限	交付 `/set-up-machine` 的 rule table 行；合并后，更新已安装的 skills，并在每台机器上重新运行 `/set-up-machine` 。
个人变更	让用户在 workstation repo 中提交并推送，然后将其拉取到 clone 中，并在每台机器上重新运行 `/set-up-machine` 。
没有 workstation repo 的全局指令	在每台机器上重新运行 `/set-up-machine` ；每个 harness 都会读取同一个共享文件。
项目指令或项目权限	在项目中提交。如果某项标准配置由所有项目共享，则改为修改 `/set-up-project` ，并在每个项目中重新运行它。
source repo 中的 skill	完成交付；合并后，在每台机器上的每个安装了它的 scope 中运行 `npx skills update <name>` 。如果某台机器的 workstation repo 在 `agents/installs.json` 中列出了该 skill，运行 `/set-up-machine` 时也会为它获取更新。
local skill	与项目一同提交。
set-up skill 本身	先将其作为 skill 变更处理，然后在所有适用位置重新运行该 set-up skill。

当用户询问运行某个 skill 的成本，或如何降低成本时，遵循

efficiency-analysis.md

。

References

参考资料

skill-operations.md: the kinds of skill, and creating, installing, updating, moving, removing, forking, upgrading a fork, shipping, auditing and publishing them.
efficiency-analysis.md: measuring what one run of a skill costs, and making the next run cheaper.

skill-operations.md：skill 的类型，以及创建、安装、更新、移动、移除、fork、升级 fork、交付、审计和发布 skill 的方法。
efficiency-analysis.md：衡量运行一次 skill 的成本，以及如何降低下一次运行的成本。

Scripts

脚本

scripts/session-usage.py: token and time use of a session transcript, split at given moments, for the efficiency analysis.

scripts/session-usage.py：按给定时点切分 session transcript，统计 token 与时间用量，以供 efficiency analysis 使用。