write-agent-instructions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write agent instructions

编写 Agent 指令

Agent instructions are text a model or agent executes: skills and slash commands,

AGENTS.md

and

CLAUDE.md

, system and developer prompts, and task prompts written for an agent. In a mixed artifact, such as a prompt inside application code, change only the instruction content; the repository's own workflow owns code integration and runtime checks.

Agent 指令是模型或 Agent 执行的文本，包括 skill 和 slash command、

AGENTS.md

和

CLAUDE.md

、system prompt 和 developer prompt，以及为 Agent 编写的 task prompt。对于混合型产物，例如应用程序代码中的 prompt，只修改指令内容；代码集成和运行时检查由仓库自身的工作flow负责。

Boundaries

边界

Answer planning-only requests in conversation: plans, designs, critiques, outlines, and discussions of instruction structure. For mixed requests, resolve the plan first and write files once the implementation path is clear.
Treat named tools, skills, frameworks, and workflows as context for the plan; switch to file creation only on the user's explicit ask. When file-writing intent is ambiguous and edits would be surprising, ask before editing.
A review-only or evaluation-only request stays read-only: check the artifact against this skill's rules and report findings in conversation.
Existing explicit authorization carries forward. Ask only about unresolved scope or material preferences.

在对话中回答仅涉及规划的请求，包括计划、设计、批评、大纲以及对指令结构的讨论。对于混合型请求，先明确方案，待实现路径清晰后再写入文件。
将提及的 tool、skill、framework 和 workflow 视为规划背景；只有用户明确要求时，才切换到创建文件。若写入文件的意图不明确，且编辑可能令人意外，则先询问再编辑。
仅审查或仅评估的请求保持只读：根据本 skill 的规则检查产物，并在对话中报告发现。
既有明确授权继续有效。仅就尚未解决的范围或实质性偏好进行询问。

References

参考资料

Load a reference at the step named here when its condition holds, or where another pointer names it.

Reference	Step	Load when
`references/skill-mechanics.md`	1	Creating or reviewing a skill or slash command, or changing its name, invocation, description, packaging, bundled scripts, interfaces, or how its body tells the agent to run a bundled script. Not for other changes to body wording.
`references/pruning-instructions.md`	2	Pruning, renaming, or structurally reorganizing an existing artifact, including changes to its required sections, ordering, output formats, or loading behavior; recommending such a change in a review; or uncertainty about whether a change is structural.
`references/context-design.md`	4	Designing or changing retrieval or loading paths, such as choosing which sources an agent reads or retrieves at run time, moving an existing artifact's material into or out of a conditional reference, adding a load condition, or changing which branches reach an existing pointer's target; designing retained context or continuation state; an explicit request to design context management; or uncertainty about one of these decisions. Rewording a condition without changing its target or the branches it covers, and the ordinary placement of a new skill's own references, follow step 4 alone. A persistent file, a long task, or several agents are not reasons on their own.
`references/evaluating-instructions.md`	1 for an explicit evaluation request, otherwise 5 or 6	An explicit evaluation request, a consequential authorized behavior change (a removed, added, or changed safeguard or approval gate, consumer format, ordering, or load condition), a disputed no-op, or a change to an existing description or pointer condition that alters which cases reach it. Use the section that applies.

在以下指定步骤满足相应条件时加载相应 reference；若其他 pointer 指向某个 reference，也应加载。

Reference	步骤	加载条件
`references/skill-mechanics.md`	1	创建或审查 skill 或 slash command，或更改其名称、调用方式、描述、打包方式、随附脚本、interface，或其正文指示 Agent 运行随附脚本的方式。其他仅修改正文措辞的更改不适用。
`references/pruning-instructions.md`	2	精简、重命名或对现有产物进行结构重组，包括更改其必需章节、顺序、输出格式或加载行为；在审查中建议此类更改；或不确定某项更改是否属于结构性更改。
`references/context-design.md`	4	设计或更改检索或加载路径，例如选择 Agent 在运行时读取或检索哪些来源，将现有产物的材料移入或移出 conditional reference，添加加载条件，或更改哪些分支可以到达现有 pointer 的目标；设计保留的上下文或 continuation state；明确要求设计上下文管理；或不确定上述决策。仅改写条件但不改变其目标或覆盖的分支，以及新 skill 自身 references 的常规放置，仅遵循步骤 4。持久文件、长任务或多个 Agent 本身不构成加载理由。
`references/evaluating-instructions.md`	明确提出评估请求时为 1，否则为 5 或 6	明确提出评估请求；经授权且影响重大的行为更改，例如移除、新增或更改 safeguard、approval gate、consumer format、ordering 或 load condition；有争议的 no-op；或更改现有 description 或 pointer condition，从而改变哪些情况会触发它。使用其中适用的章节。

Workflow

工作流

Identify the job.
- Name the artifact, the agent that executes it, the outcome the user wants, and the operation: create, wording edit, structural revision including pruning, review, or evaluation.
- A wording edit, such as shortening or polishing, keeps every requirement. Removing, merging, or reordering requirements is a structural revision; make one only when the request calls for it.
Gather the material.
- Ground new instructions in completed tasks, user corrections, project docs, runbooks, schemas, review comments, issues, or patches, and identify what the executing agent gets wrong without them.
- For an existing artifact, its current requirements are the baseline: explicit user preferences, constraints and permissions, necessary ordering, safeguards, and formats its consumers rely on.
- When deciding where material lives, establish how the executing agent receives the artifact and what it can read, from the request, project docs, or the code that loads it.
- Before writing a lesson as an instruction, check whether a lint rule, type, runtime check, script, or hook can enforce it. When enforcement fits in the artifact's own files, put it there and omit the prose rule; when it belongs in the target repo, recommend it rather than editing beyond the artifact.
- Separate judgment and approval from mechanical steps, and give each mechanical step a script or a direct command where the executor can run one, choosing per the Scripts section of
```
references/skill-mechanics.md
```
  when the choice is unclear.
Write for the outcome. Write each rule in the fewest words that state it; add detail or an example only for a failure you can name.
- Start with what a finished run delivers and its required content. List terminal outcomes when the work can end more than one way; for audit, review, and maintenance work, include "nothing worth changing" as a complete result without padding the report.
- Use ordered steps when sequence matters. Prescribe other steps, fixed headings, or templates only for fragile operations, cases the agent gets wrong by default, or formats another skill or tool consumes. Otherwise state the outcome and constraints; let the agent choose the method and form.
- Give steps and sets of rules a checkable completion criterion where one naturally exists; prefer exhaustive phrasing ("every changed file reviewed") over vague phrasing ("review the changes"). Name concrete checks for judgment outcomes instead of forcing artificial metrics.
- Anchor recurring concepts on leading words: established terms the user's prompts and the domain already use, repeated as the same token throughout. Collapse spelled-out enumerations and paraphrases into the word. Define a coined term where it first appears.
- Write plain, precise sentences with concrete actions. Keep commands, flags, paths, and identifiers exact, and state real uncertainty.
- State the target behavior. Keep a prohibition only as a guardrail, paired with what to do instead.
- Write every line for the executing agent. Omit authoring rationale, request history, and explanations of the artifact's shape; keep a reason only when it informs a call the agent must make unaided. Write decided values, never verification status or staged values ("start at X, lower after measurement"); when a value is undecided, ask before writing.
- Avoid time-sensitive facts unless the instructions say how to refresh them.
- Keep a concept's definition, rules, and caveats together under one heading. Make defaults clear; mention alternatives only when they change a decision.
- Make the workflow batch independent operations into one tool round. Batches stop at steps that need judgment or user authorization, and failures stay visible.
- Make included examples concrete and realistic.
- A rule the user dictates goes in as one line in the file's own terms, as short as its neighbours, with no examples or directives they did not give.
- Prefer instructions that work with no other skill installed. When the workflow needs another skill or document, name it and load it at the step that uses it, rather than copying or summarizing its guidance.
Place the material.
- Always-loaded text, such as an instruction file, a system prompt, or a model-invoked skill's description, returns on every later request that retains or reassembles it and in every agent context that inherits it. Text loaded on demand may also stay for later turns. Give always-loaded text the strictest retention bar.
- Keep what every run needs in the main file, including universal constraints. Move material that only some branches need behind a pointer, unless the pointer and the extra read would cost about as much as the material. A reference that every run loads organizes the text but saves no context.
- A pointer names its target and a load condition the agent can recognize without first reading the target. Write it as a plain path, such as
```
references/context-design.md
```
  , not a Markdown link, and name sections in prose, such as "the Scripts section". When a pointer fails to fire on a branch that needs its target, sharpen the wording before inlining the material.
- Place every pointer target where the executing agent can retrieve it. Before moving material out of the text that agent receives, confirm that agent will reach the new location and add the pointer or loading step that gets it there. When you cannot confirm that, keep the material inline, supply it with the task, or ask how to deliver it.
- Count the full read path: the main file plus every reference, skill, and inherited instruction a run loads, including
```
refine-it
```
  and
```
shorten-it
```
  when used. Loading a reference adds to context and clears nothing earlier.
- Weigh agent context against human load: material with no pointer depends on the human remembering to invoke it. Spend that load only where human judgment matters.
- Treat a long main file, such as a
```
SKILL.md
```
  body over ~100 non-empty lines, as a sign that branch material belongs behind a pointer, not as a length target; completeness and correctness outrank size. Reduce the main file by moving branch material, not by fragmenting text or adding headings.
Prune, then polish.
- When creating an artifact or making a structural revision, remove within the requested scope the requirements and sub-steps the agent can reliably infer from the outcome, whole sentences that change no behavior relative to the executing agent's default, and material that no longer bears on the task.
- Preserve explicit user preferences, necessary ordering, consumer-required formats, and safeguards against specific likely or costly failures. A stated user preference stays even if the agent would follow it unprompted; if it predates the request, list it as a suggested removal. Keep a safeguard only when you can name the failure and why the executing agent's default would miss it. Keep each retained requirement's meaning exactly; report an ambiguity you notice instead of resolving it in the artifact.
- Before removing a rule because another source covers it, confirm the source applies everywhere the rule does, including tasks an exception or load condition excludes from it; otherwise keep the rule for the uncovered cases or ask; don't widen where the other source applies to make it cover them.
- In a wording edit, report pure emphasis that the polish cuts as a removal.
- Name the action, not the steps the agent takes on its own: "apply
```
references/x.md
```
  ", not "read and apply
```
references/x.md
```
  ". State each rule once, where it applies; merge duplicates, including gotchas that merely negate a workflow rule.
- Load
```
refine-it
```
  , then
```
shorten-it
```
  , and run each over the whole of every instruction artifact created or structurally revised, and over the changed text of other edits, or the whole artifact when the request is artifact-wide. Polish text the user supplied as well, unless they asked for it verbatim.
- Name each command, tool, and path once, as what its step acts on. An identifier in parentheses after words that name the same thing is a duplicate: rewrite "load settings from the config file (
```
config.yaml
```
  )" as "load settings from
```
config.yaml
```
  ", and "upload the build (
```
aws s3 cp
```
  , the deploy skill)" as "upload the build with
```
aws s3 cp
```
  , which the deploy skill documents". Keep what the identifier does not say, such as purpose, conditions, arguments, or where it is documented.
- Compare the polished text with the post-pruning draft. Restore any change the polish introduced to triggers, requirements, permissions, workflow order, or other operational meaning. Leave wording unchanged where neither pass improves it.
Check and report.
- Check the artifact against its job and every format a consumer requires. Keep terminology consistent across the main file and its references, and verify each pointer, documented command, argument, and output against its target.
- A wording edit needs a meaning review, not behavior runs. Outside the evaluation reference's conditions, suggest useful behavior checks rather than running them.
- Report what changed, each intentionally removed requirement separately from wording changes, suggested removals, the checks performed, and material limits.

明确任务。
- 指明产物、执行它的 Agent、用户期望的结果以及操作类型：创建、措辞编辑、包括精简在内的结构修订、审查或评估。
- 措辞编辑，例如缩短或润色，应保留每项要求。删除、合并或重排要求属于结构修订；仅当请求明确要求时进行。
收集材料。
- 将新指令建立在已完成任务、用户纠正、项目文档、runbook、schema、审查意见、issue 或 patch 的基础上，并找出缺少这些材料时执行 Agent 会犯的错误。
- 对于现有产物，其当前要求是基线，包括明确的用户偏好、约束和权限、必要顺序、safeguard，以及 consumer 所依赖的格式。
- 在决定材料放置位置时，根据请求、项目文档或加载产物的代码，确定执行 Agent 如何接收该产物以及它能够读取什么。
- 在把一条经验写成指令之前，检查是否可以通过 lint rule、type、runtime check、script 或 hook 强制执行。当这种强制机制适合产物自身的文件时，将其放在那里并省略文字规则；当它属于目标仓库时，只作建议，而不编辑产物之外的内容。
- 将判断和审批与机械步骤分离；对于执行者可以运行的每个机械步骤，提供 script 或直接命令。选择不明确时，遵循
```
references/skill-mechanics.md
```
  的 Scripts 章节。
围绕结果编写。每条规则都使用能够完整表达其含义的最少词语；仅针对能够明确指出的失败添加细节或示例。
- 从一次成功运行应交付什么及其必需内容开始。当工作可能有多种结束方式时，列出最终结果；对于 audit、review 和 maintenance 工作，将「没什么值得修改」视为完整结果，不要为报告填充内容。
- 顺序重要时使用有序步骤。仅对脆弱操作、Agent 默认容易做错的情况，或其他 skill 或 tool 消费的格式，规定其他步骤、固定标题或模板。否则陈述结果和约束，让 Agent 选择方法和形式。
- 在自然存在的地方，为步骤和规则集合提供可检查的完成标准；优先使用穷尽式表述，例如「每个已修改文件都已审查」，而非模糊表述，例如「审查这些更改」。对于判断类结果，应指出具体检查项，不要强加人为指标。
- 用首词锚定反复出现的概念：使用用户 prompt 和领域已经采用的既定术语，并始终以同一词重复。折叠拼写出来的枚举和释义，统一使用该词。新造术语首次出现时定义。
- 使用平实、精确且包含具体动作的句子。命令、flag、path 和 identifier 保持准确，并如实表达不确定性。
- 陈述目标行为。禁止项仅作为 guardrail 使用，并同时说明应改为做什么。
- 每一行都写给执行 Agent。省略编写理由、请求历史和对产物形态的解释；仅当理由能帮助 Agent 独立作出判断时保留。写入已决定的值，绝不写入验证状态或暂定值，例如「从 X 开始，测量后降低」；如果某个值尚未决定，先询问再写入。
- 避免时效性事实，除非指令说明了刷新方式。
- 将一个概念的定义、规则和注意事项放在同一标题下。明确默认值；仅当替代方案会改变决策时才提及。
- 使 workflow 将相互独立的操作批量合并到一次 tool round。批次在需要判断或用户授权的步骤处停止，并保持失败可见。
- 使所含示例具体且真实。
- 用户指定的规则应按文件自身的术语以一行写入，长度与相邻行一致，不添加用户未提供的示例或指令。
- 优先选择无需安装其他 skill 即可工作的指令。当 workflow 需要另一个 skill 或文档时，指定它，并在使用该 skill 或文档的步骤加载，而不是复制或总结其指导。
放置材料。
- 始终加载的文本，例如 instruction file、system prompt，或 model 调用的 skill 的 description，会出现在之后每个保留或重新组装它的请求中，也会出现在继承它的每个 Agent 上下文中。按需加载的文本也可能留存到后续轮次。对始终加载的文本采用最严格的保留标准。
- 将每次运行都需要的内容保留在主文件中，包括通用约束。除非 pointer 及其额外读取成本与材料本身大致相当，否则将仅部分分支需要的内容移到 pointer 之后。每次运行都会加载的 reference 只是组织文本，并不节省上下文。
- pointer 应说明其目标，以及 Agent 无需先读取目标即可识别的加载条件。将其写成普通 path，例如
```
references/context-design.md
```
  ，而不是 Markdown link；用普通文本提及章节，例如「Scripts 章节」。当 pointer 在需要目标的分支上未触发时，先强化措辞，再将材料内联。
- 将每个 pointer target 放在执行 Agent 可以检索到的位置。在将材料移出 Agent 接收的文本前，确认 Agent 能到达新位置，并添加能将其引至该处的 pointer 或加载步骤。无法确认时，让材料保持内联、随任务提供，或询问如何交付。
- 计算完整读取路径：主文件加上每次运行加载的每个 reference、skill 和继承指令，包括使用时的
```
refine-it
```
  和
```
shorten-it
```
  。加载 reference 会增加上下文，且不会清除先前内容。
- 在 Agent 上下文与人的负担之间权衡：没有 pointer 的材料依赖人记住并调用它。只在人的判断确实重要的地方施加这种负担。
- 将过长的主文件，例如超过约 100 个非空行的
```
SKILL.md
```
  正文，视为分支材料应放在 pointer 之后的信号，而不是长度目标；完整性和正确性优先于体积。通过移动分支材料来缩减主文件，而不是拆散文本或添加标题。
先精简，再润色。
- 创建产物或进行结构修订时，在请求范围内删除 Agent 可根据结果可靠推断的要求和子步骤、相对于执行 Agent 的默认行为不会改变任何行为的整句内容，以及与任务不再相关的内容。
- 保留明确的用户偏好、必要的顺序、consumer 要求的格式，以及针对具体、可能发生或代价高昂的失败的 safeguard。用户声明的偏好即使 Agent 未经提示也会遵循也应保留；如果它早于当前请求，则列为建议删除项。仅当你能指出具体失败，以及执行 Agent 的默认行为为何会遗漏该失败时，才保留 safeguard。保留每项要求的确切含义；发现歧义时应报告，而不是在产物中自行消除歧义。
- 在因另一来源已涵盖而删除某条规则之前，确认该来源在原规则适用的所有场景都适用，包括原规则被 exception 或 load condition 排除的任务；否则，为未覆盖场景保留该规则或进行询问；不要扩大另一来源的适用范围来强行覆盖。
- 在措辞编辑中，将润色过程中删去的纯强调内容报告为删除。
- 指明动作，而不是 Agent 自主执行的步骤：写「应用
```
references/x.md
```
  」，而不是「读取并应用
```
references/x.md
```
  」。每条规则只陈述一次，并放在其适用位置；合并重复内容，包括仅否定某条 workflow 规则的注意事项。
- 先加载
```
refine-it
```
  ，再加载
```
shorten-it
```
  ，并对每个新建或结构性修订的完整指令产物，以及其他编辑中发生更改的文本运行二者；若请求针对整个产物，则对整个产物运行。除非用户要求逐字保留，否则也润色用户提供的文本。
- 每个 command、tool 和 path 只按其步骤所作用的对象提及一次。若词语与其后的 identifier 指同一事物，则属于重复：把「从 config 文件加载设置（
```
config.yaml
```
  ）」改写为「从
```
config.yaml
```
  加载设置」，把「上传构建产物（
```
aws s3 cp
```
  ，deploy skill）」改写为「使用
```
aws s3 cp
```
  上传构建产物，具体方式见 deploy skill 的文档」。保留 identifier 未表达的信息，例如用途、条件、参数或记录位置。
- 将润色后的文本与精简后的草稿比较。恢复润色引入的任何触发条件、要求、权限、workflow 顺序或其他操作语义变化。若两轮处理均未改进，则保持措辞不变。
检查并报告。
- 根据产物用途及 consumer 要求的每种格式检查产物。确保主文件与其 references 中术语一致，并针对目标核验每个 pointer、记录的 command、argument 和 output。
- 措辞编辑需要语义审查，而不是行为运行。在 evaluation reference 的适用条件之外，建议执行有价值的行为检查，而不要直接运行。
- 报告更改内容；将每项有意删除的要求与措辞更改分别列出；列出建议删除项、已执行的检查以及材料限制。