maintain-environment

维护环境

环境是 Agent 运行所依赖的内容：权限、全局指令、项目指令和技能。此技能是修改环境的起点。选择修改所属的来源，然后遵循该来源自己的指南。若要设置机器或项目，请改用 /set-up-machine 或 /set-up-project。

• **每项修改只在其来源处编写一次，**这样以后修改时只需改一处。
• **不要在公开文件中放入个人细节。**技能仓库和大多数项目都是公开的。姓名、账户、用户机器上的路径及其他项目的信息只能放在工作站仓库中；如果机器上没有工作站仓库，则放在共享的全局指令文件中。在技能或公开的 AGENTS.md 中，应将细节概括化，或将其设为参数。
• **关闭运行框架的记忆功能。**其他运行框架看不到记忆，而且记忆位于所有仓库之外。应将原本要存入记忆的内容写入某个来源。

参数

• <skills-repo>：用户在 GitHub 上自己的技能仓库，格式为 owner/repo。
• <path-to-skills-repo>：该仓库的克隆路径。
• <workstation-repo>：用户用于个人 Agent 设置的仓库，通常为私有仓库，格式为 owner/repo。
• <path-to-workstation-repo>：该仓库的克隆路径，例如 ~/code/agent-setup。

修改应放在哪里

由两个问题决定来源：谁需要它——仅此用户、某个项目中的任何人，还是执行任务的任何 Agent？它必须强制执行，还是仅提供指引？表格按强制程度从高到低排列。沿表格向下查找，并使用第一个符合条件的行。

修改	来源	指南
适用于所有人的规则：拒绝、询问或允许并报告	<skills-repo> 中 /set-up-machine 的 rules.json	<path-to-skills-repo>/docs/design/set-up-machine.md，也适用于对 /set-up-machine 的任何其他修改
仅此用户需要的内容：工作约定或工作流条目、某个角色使用的工具、个人权限、运行框架默认设置、插件、每台机器都要安装的内容	<workstation-repo>，其克隆位于 <path-to-workstation-repo>	该仓库的 DESIGN.md：参照其中指定文件的结构
某个项目中的队友需要的内容	项目的 AGENTS.md，并让 CLAUDE.md 包含 @AGENTS.md；项目只能新增允许项	项目的 AGENTS.md
任何团队的工具如何完成某项任务	<skills-repo> 中的技能，或某个项目中的本地技能	若存在，则参考 <path-to-skills-repo>/docs/design/<skill>.md，以及 references/skill-operations.md

• **如果某项细节只适用于技能的部分运行：**将其放在 SKILL.md 旁边的参考文档中。在正文中说明何时阅读该文档，并在结尾添加 ## References 行，说明其涵盖的内容。
• **如果用户没有工作站仓库：**将个人指令写入共享文件本身。个人权限没有合适的存放位置，因此请按 references/workstation.md 所述，提议创建工作站仓库。
• 如果此机器没有指针（~/.config/agents/source.md）：先运行 /set-up-machine，由它创建该文件。
• **如果用户要求改进其工作流：**阅读 <path-to-workstation-repo>/AGENTS.md 及其中指定的文档，例如用户的原则。进行修改前，指出每项与修改相冲突的原则。

**团队测试。**设想一位队友使用另一个运行框架、另一个会话宿主，并在已通过 /set-up-machine 设置但没有用户个人工作流的机器上工作。修改完成后，他们仍必须只凭项目指令、技能以及 /set-up-machine 写入的角色，就能在用户的任何项目中工作。因此，队友需要的内容不得放在全局指令中，任何技能也不得依赖用户的默认工具。不同设置之间会变化的值，应在技能中设为 <kebab-case> 参数；新增角色则应先加入 /set-up-machine 的角色表。将每项不符合要求的内容移到表格中适用的行。

步骤

1. 选择对应行，并根据团队测试检查变更。
2. 按照指南，在源位置进行变更。使用 /writing-for-agents 编写每条指令和技能。在技能的源代码仓库中修改已安装的技能，切勿修改已安装的副本，否则下次运行 npx skills update 时会覆盖变更。
3. 如果变更涉及全局指令，请向用户展示完整的共享文件，并标记每一行变更。在提交或发布之前等待用户批准，因为这些内容会影响每个 Agent。
4. 更改技能后，运行团队测试审计。针对用户环境默认配置中的每个工具，以及“environment defaults”，对技能进行 Grep 搜索。跳过每个工具自身的技能、两个设置技能和当前技能。
   • 当技能自行选择工具时： 将其改为参数，并把该工具的命令移至工具自身的技能中。
   • 当它是示例或数据时： 保留。
   • 当它提到环境默认配置时： 删除该提及。
5. 通过 /to-pr 在分支上提交技能仓库变更，发起拉取请求，然后停止。由用户合并，或由用户要求你合并。
6. 按下表所述，将变更应用到各处。npx skills 会从默认分支安装，因此安装和更新要在合并后运行。
7. 报告本次会话无法完成的每个步骤，并说明它是在这台机器、其他每台机器还是每个项目中运行。

变更	如何应用到各处
适用于所有人的规则或设置技能	合并后，运行 npx skills update，然后在每台机器上重新运行 /set-up-machine，或在每个项目中重新运行 /set-up-project。
个人变更	用户提交并推送。每台机器拉取后重新运行 /set-up-machine。
没有关联工作站仓库的全局指令	在每台机器上重新运行 /set-up-machine。
项目指令或权限	在项目中提交。对于每个项目都共享的通用规则，修改 /set-up-project，并在每个项目中重新运行。
源代码仓库中的技能	合并后，在安装该技能的每个作用域、每台机器上运行 npx skills update <name>。工作站仓库中列有该技能的机器，也会通过 /set-up-machine 获取它。
本地技能	在项目中一并提交。

当用户询问运行某项技能的成本时，请遵循 references/efficiency-analysis.md。

参考资料

• references/skill-operations.md：技能的类型，以及创建、安装、更新、移动、移除、分叉、发布、审计和公布技能。
• references/efficiency-analysis.md：衡量运行一次技能的成本，以及如何降低下次运行的成本。
• references/workstation.md：工作站仓库的用途，以及如何启动一个工作站仓库。

脚本

• scripts/session-usage.py：在指定时刻拆分会话记录，统计令牌和时间用量，供效率分析使用。