agents-brain

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agents Brain

Agents 核心指南

If these instructions are already present in the conversation from a slash or dollar invocation, follow them directly; do not invoke this skill again through a skill tool.

Create or polish repo-local context as one coherent system: human-facing README.md files, agent-facing AGENTS.md files with companion CLAUDE.md symlinks, existing project-installed skills under

.agents/skills

, eligible source-catalog skills under

skills/<name>/

, and context docs — any other Markdown files, under any name or directory, whose content is durable guidance for agents or humans, such as conventions, command catalogs, data-format rules, workflow runbooks, and reference material.

Success means every selected target is grounded in repository evidence, respects its audience and scope, spends agent context only on guidance that changes behavior, and passes the narrowest repository-defined validation. Stop after reporting completed or planned changes, validation, and any blockers.

如果对话中已经存在通过斜杠或美元符号调用的这些指令，请直接遵循；不要通过技能工具再次调用此技能。

将仓库本地上下文创建或完善为一个连贯的系统：面向人类的README.md文件、面向Agent的AGENTS.md文件（附带CLAUDE.md符号链接）、

.agents/skills

下已有的项目安装技能、

skills/<name>/

下符合条件的源目录技能，以及上下文文档——任何名称或目录下的其他Markdown文件，其内容为面向Agent或人类的持久化指南，例如约定、命令目录、数据格式规则、工作流手册和参考资料。

成功的标准是：每个选定的目标都基于仓库证据、尊重其受众和范围、仅将Agent上下文用于能改变行为的指南，并且通过最严格的仓库定义验证。完成后报告已完成或计划的更改、验证情况以及任何阻碍因素即可停止。

Model and Context Optimization

模型与上下文优化

Optimize skills and other agent-facing context for GPT-5.6 and Claude Fable 5 while preserving README.md as clear human-facing documentation. Before complex, long-running, multi-tool, or orchestration-heavy context work, resolve

scripts/fetch-guidance.sh

relative to this skill directory, run it once for

gpt-5p6

and once for

claude-fable-5

, and read both returned files completely. The helper retrieves the official GPT-5.6 prompting guidance and Claude Fable 5 prompting guidance because their recommendations may evolve. Simple context work does not require either guide.

Accept an integrity-valid

cached

guide for 24 hours. Use

--refresh

for explicitly latest or change-sensitive work, materially disputed guidance, or conflicts with observed model behavior. Interpret helper diagnostics precisely:

```
cached
```
reused a guide validated no more than 24 hours ago without network access.
```
revalidated
```
refreshed validation metadata after a successful conditional
```
304
```
response.
```
fetched
```
atomically replaced the cache with integrity-valid content from the pinned official URL.
```
stale
```
reused a guide validated no more than seven days ago after live retrieval failed. Proceed only after reading it and disclose the validation timestamp and retrieval failure in the final risks.

Forced refreshes, expired entries, integrity failures, and unexpected redirects fail closed. If either required guide cannot be returned, stop qualifying work before writing instead of substituting memory or another source. Never create the cache in a repository or skill installation.

Keep only content that changes a decision, prevents an evidenced mistake, or supplies a non-discoverable constraint. State each meaning once at the narrowest reliable load scope, except where independently installed artifacts need to stay self-contained. Preserve authority, safety, material exceptions, semantic success criteria, and exact machine-consumed text. Documentation-only authority does not permit changing helpers or schemas; report an extraction opportunity instead.

在保持README.md为清晰的面向人类文档的同时，针对GPT-5.6和Claude Fable 5优化技能及其他面向Agent的上下文。在进行复杂、长期、多工具或编排密集型的上下文工作之前，相对于此技能目录解析

scripts/fetch-guidance.sh

，针对

gpt-5p6

和

claude-fable-5

各运行一次，并完整阅读返回的两个文件。该助手会获取官方的GPT-5.6提示指南和Claude Fable 5提示指南，因为它们的建议可能会不断演变。简单的上下文工作无需参考任何指南。

接受经过完整性验证的“cached”指南，有效期为24小时。对于明确需要最新内容或对变化敏感的工作、存在实质性争议的指南，或与观察到的模型行为冲突的情况，使用

--refresh

参数。精准解读助手的诊断信息：

```
cached
```
：复用了不超过24小时前验证过的指南，无需网络访问。
```
revalidated
```
：在成功获取条件式
```
304
```
响应后刷新了验证元数据。
```
fetched
```
：原子性地用来自固定官方URL的完整性验证内容替换了缓存。
```
stale
```
：在实时获取失败后，复用了不超过7天前验证过的指南。只有在阅读过该指南后才能继续，并在最终风险报告中披露验证时间戳和获取失败的情况。

强制刷新、过期条目、完整性失败和意外重定向会导致工作终止。如果无法获取任一所需指南，请在写入前停止相关工作，不要用记忆或其他来源替代。切勿在仓库或技能安装目录中创建缓存。

仅保留能改变决策、防止已证实的错误或提供不可发现约束的内容。在最窄的可靠加载范围内仅陈述一次含义，除非独立安装的工件需要保持自包含。保留权威性、安全性、重要例外、语义成功标准和精确的机器可读文本。仅文档的权威性不允许修改助手或架构；应报告提取机会。

Choose a Workflow

选择工作流

Choose exactly one workflow and read only its reference.

For skill creation, first inspect applicable repository instructions. When they define a source catalog and lifecycle, stop and follow that repository-owned workflow. Use

skill-writing

only when no catalog-specific workflow exists.

User intent	Workflow	Reference
Update, refresh, sync, prune, polish, repair, or fix context	`polish`	`references/polish.md`
Create, initialize, generate, or regenerate context files	`create`	`references/create-docs.md`
Audit, check, review, inspect, or suggest changes without edits	`polish` in `--dry-run` mode	`references/polish.md`
Create or scaffold a skill	Stop	Use repository catalog lifecycle or `skill-writing`
Install, discover, remove, or rename a skill	Stop	Use a dedicated skill-management workflow

If the intent is unclear, select

polish

--dry-run

mode and report the smallest useful planned change set.

选择恰好一个工作流并仅阅读其参考文档。

创建技能时，首先检查适用的仓库指令。当仓库定义了源目录和生命周期时，请停止并遵循该仓库自有工作流。仅当不存在特定于目录的工作流时，才使用

skill-writing

。

用户意图	工作流	参考文档
更新、刷新、同步、修剪、完善、修复上下文	`polish`	`references/polish.md`
创建、初始化、生成或重新生成上下文文件	`create`	`references/create-docs.md`
审核、检查、审查、检查或建议更改但不进行编辑	`polish` （ `--dry-run` 模式）	`references/polish.md`
创建或搭建技能框架	停止	使用仓库目录生命周期或 `skill-writing`
安装、发现、移除或重命名技能	停止	使用专用的技能管理工作流

如果意图不明确，请选择

polish

的

--dry-run

模式，并报告最小的有用计划更改集。

Authority

权限

Explicit create, update, polish, repair, fix, or equivalent intent authorizes in-scope local writes. Inspection-only intent and
```
--dry-run
```
do not.
Require explicit confirmation before deleting README.md, AGENTS.md, CLAUDE.md, or context-doc targets.
```
--force
```
authorizes documented overwrites, not deletions.
Treat a broad write request as authorization for the requested scope. Otherwise, preview a change set larger than a handful of files and stop before writing.
Do not expand from documentation work into source changes, skill creation, or external writes.

明确的创建、更新、完善、修复或等效意图授权进行范围内的本地写入。仅检查意图和
```
--dry-run
```
模式不授权写入。
删除README.md、AGENTS.md、CLAUDE.md或上下文文档目标前，需要明确确认。
```
--force
```
参数仅授权文档覆盖，不授权删除。
将宽泛的写入请求视为对请求范围的授权。否则，预览超过少量文件的更改集并在写入前停止。
不要从文档工作扩展到源代码更改、技能创建或外部写入。

Arguments

参数

```
path
```
: Optional repo-relative subtree. Restrict documentation, package-root, project-skill, source-catalog skill, and context-doc discovery to that subtree.
```
target ...
```
: Optional filters during
```
polish
```
: skill names from existing
```
.agents/skills/<name>/
```
or eligible
```
skills/<name>/
```
trees, or repo-relative Markdown paths selecting specific context docs.
```
--root-only
```
: Select only root README.md, AGENTS.md, and CLAUDE.md targets. Exclude project-installed skills, source-catalog skills, and context docs unless explicitly selected by
```
target
```
.
```
--dry-run
```
: Report planned writes and concise diffs without changing files.
```
--preserve
```
: During
```
polish
```
, keep accurate user-authored prose and structure; fix only drift and obvious noise.
```
--minimal
```
: Produce the smallest context that still meets the completion bar.
```
--thorough
```
/
```
--full
```
: Perform deeper analysis only where it adds durable, repository-specific context.
```
--force
```
: During
```
create
```
, regenerate existing README.md or AGENTS.md targets without prompting. Never applies to skills or deletions.

--minimal

and

--thorough

--full

are both present, make no writes and ask the user to choose. Report unrecognized flags; continue only when they cannot change scope, safety, or write behavior.

```
path
```
：可选的仓库相对子目录。将文档、包根目录、项目技能、源目录技能和上下文文档的发现范围限制在该子目录内。
```
target ...
```
：
```
polish
```
期间的可选过滤器：来自现有
```
.agents/skills/<name>/
```
或符合条件的
```
skills/<name>/
```
目录的技能名称，或选择特定上下文文档的仓库相对Markdown路径。
```
--root-only
```
：仅选择根目录下的README.md、AGENTS.md和CLAUDE.md目标。排除项目安装技能、源目录技能和上下文文档，除非通过
```
target
```
明确选择。
```
--dry-run
```
：报告计划的写入内容和简洁的差异，但不修改文件。
```
--preserve
```
：在
```
polish
```
期间，保留准确的用户编写的文本和结构；仅修复偏差和明显的错误。
```
--minimal
```
：生成仍能满足完成标准的最小上下文。
```
--thorough
```
/
```
--full
```
：仅在能添加持久化、仓库特定上下文的地方进行更深入的分析。
```
--force
```
：在
```
create
```
期间，无需提示即可重新生成现有的README.md或AGENTS.md目标。绝不应用于技能或删除操作。

如果同时存在

--minimal

和

--thorough

--full

，请不要进行任何写入，并要求用户选择。报告无法识别的标志；仅当它们不会改变范围、安全性或写入行为时才继续。

Repository Guard Rail

仓库防护机制

Run before discovery or writes:

cwd="$(pwd -P)"
case "$cwd" in
  /) printf 'abort: refusing to run at the filesystem root\n' >&2; exit 1 ;;
esac
repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
  printf 'abort: not inside a git repository\n' >&2; exit 1; }
managed_skill_root=
case "$repo_root" in
  /|"$HOME") printf 'abort: unsupported repo root: %s\n' "$repo_root" >&2; exit 1 ;;
  "$HOME/.agents"|"$HOME/.codex"|"$HOME/.claude") managed_skill_root="$repo_root/skills" ;;
  "$HOME/.agents/"*|"$HOME/.codex/"*|"$HOME/.claude/"*)
    printf 'abort: repo root is nested under an agent configuration repository: %s\n' "$repo_root" >&2; exit 1 ;;
esac
if [ -n "$managed_skill_root" ]; then
  case "$cwd" in
    "$managed_skill_root"|"$managed_skill_root/"*)
      printf 'abort: installed skills must be edited in their source catalog: %s\n' "$cwd" >&2; exit 1 ;;
  esac
fi

When

managed_skill_root

is set, allow README.md, AGENTS.md, and CLAUDE.md work elsewhere in that repository, but exclude the entire installed

skills/

tree from every workflow. Apply the exclusion before discovery, canonicalization, or symlink traversal. If

path

, a

target

, or an explicit request would enter that tree, make no writes there and report that the skill must be edited in its source catalog.

--force

does not override this boundary.

Outside managed agent-config roots, eligible git-tracked

skills/<name>/

source catalogs are in scope for

polish

per

references/polish.md

Snapshot

git status --short

before broad edits. Preserve unrelated pre-existing changes and re-check expected paths after generators or broad commands.

在发现或写入前运行：

cwd="$(pwd -P)"
case "$cwd" in
  /) printf 'abort: refusing to run at the filesystem root\n' >&2; exit 1 ;;
esac
repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
  printf 'abort: not inside a git repository\n' >&2; exit 1; }
managed_skill_root=
case "$repo_root" in
  /|"$HOME") printf 'abort: unsupported repo root: %s\n' "$repo_root" >&2; exit 1 ;;
  "$HOME/.agents"|"$HOME/.codex"|"$HOME/.claude") managed_skill_root="$repo_root/skills" ;;
  "$HOME/.agents/"*|"$HOME/.codex/"*|"$HOME/.claude/"*)
    printf 'abort: repo root is nested under an agent configuration repository: %s\n' "$repo_root" >&2; exit 1 ;;
esac
if [ -n "$managed_skill_root" ]; then
  case "$cwd" in
    "$managed_skill_root"|"$managed_skill_root/"*)
      printf 'abort: installed skills must be edited in their source catalog: %s\n' "$cwd" >&2; exit 1 ;;
  esac
fi

当设置了

managed_skill_root

时，允许在该仓库的其他位置进行README.md、AGENTS.md和CLAUDE.md相关工作，但将整个已安装的

skills/

目录排除在所有工作流之外。在发现、规范化或符号链接遍历之前应用排除规则。如果

path

、

target

或明确请求会进入该目录，请不要在那里进行任何写入，并报告必须在源目录中编辑该技能。

--force

参数不会覆盖此边界。

在托管Agent配置根目录之外，符合条件的Git跟踪

skills/<name>/

源目录属于

polish

的范围，遵循

references/polish.md

。

在进行广泛编辑前，快照

git status --short

的结果。保留无关的预先存在的更改，并在生成器或广泛命令运行后重新检查预期路径。

Discovery and Tool Routing

发现与工具路由

Use git-aware discovery, canonicalize every candidate beneath

repo_root

, and exclude VCS, dependency, environment, and build outputs. Deliberately include ignored

.agents/skills/*/SKILL.md

only when project skills are selected. Discover git-tracked, non-ignored, non-symlinked

skills/*/SKILL.md

only outside managed agent-config roots and only when source-catalog skills are selected. Parse each selected skill's YAML frontmatter. Inspect only a project-installed skill's declared write boundary before deciding whether it qualifies for a coordination exemption. Prefer

fd

, fall back once on suspiciously narrow results, and synthesize independent repository evidence before writing.

Discover context docs by following Markdown links from README.md, AGENTS.md, CLAUDE.md, and SKILL.md files, then by scanning remaining tracked Markdown whose content qualifies. Classify by content, never by file name or location. Exclude changelogs, licenses, legal and policy notices, generated or vendored documentation, and prose that is product content rather than guidance. When classification is uncertain, leave the file out of scope and report it as a candidate.

使用支持Git的发现功能，将每个候选对象规范化到

repo_root

之下，并排除版本控制系统、依赖项、环境和构建输出。仅当选择了项目技能时，才特意包含被忽略的

.agents/skills/*/SKILL.md

。仅在托管Agent配置根目录之外且选择了源目录技能时，才发现Git跟踪、未被忽略、非符号链接的

skills/*/SKILL.md

。解析每个选定技能的YAML前置元数据。在决定是否符合协调豁免条件之前，仅检查项目安装技能声明的写入边界。优先使用

fd

，如果结果异常狭窄则回退一次，并在写入前综合独立的仓库证据。

通过跟随README.md、AGENTS.md、CLAUDE.md和SKILL.md文件中的Markdown链接来发现上下文文档，然后扫描剩余的符合内容条件的跟踪Markdown文件。按内容分类，绝不按文件名或位置分类。排除变更日志、许可证、法律和政策通知、生成或供应商提供的文档，以及属于产品内容而非指南的文本。当分类不确定时，将文件排除在范围之外并报告为候选对象。

Completion and Report

完成与报告

After writes, run repository-defined Markdown formatting or checks when present. If skill frontmatter or

agents/openai.yaml

changed in a project-installed skill, run its invocation metadata check. Verify changed CLAUDE.md symlinks resolve to sibling AGENTS.md. In

--dry-run

, report commands that would depend on planned files instead of running them.

Lead with

### ✅ Context updated

only after writes and required validation pass,

### ⚠️ Context updated — validation failed

when files were written but required checks fail,

### 🔎 Context preview — no files written

in dry-run mode, or

### ⛔ Context blocked — no files written

for a pre-write stop. Then report only:

```
🧭 Mode and scope
```
: workflow, dry-run status, target counts, and relative paths in a compact table.
```
📦 Changes
```
: completed or planned changes grouped by directory; use a tree when it makes path ownership clearer.
```
🧪 Validation
```
: exact commands, result, and any justified skip in a table.
```
⚠️ Blockers and risks
```
: conflicts, advisories, and unrecognized flags; omit when empty.

Keep paths, commands, guard-rail errors, symlink targets, and user-authored content exact and undecorated. Omit empty detail and stop once the selected targets meet the completion bar.

写入后，运行仓库定义的Markdown格式化或检查（如果存在）。如果项目安装技能中的技能前置元数据或

agents/openai.yaml

发生更改，请运行其调用元数据检查。验证已更改的CLAUDE.md符号链接是否解析为同级的AGENTS.md。在

--dry-run

模式下，报告将依赖于计划文件的命令，而不是运行它们。

仅在写入和所需验证通过后，以

### ✅ 上下文已更新

开头；当文件已写入但所需检查失败时，以

### ⚠️ 上下文已更新 — 验证失败

开头；在干运行模式下以

### 🔎 上下文预览 — 未写入任何文件

开头；对于写入前停止的情况，以

### ⛔ 上下文被阻止 — 未写入任何文件

开头。然后仅报告：

```
🧭 模式与范围
```
：工作流、干运行状态、目标数量和相对路径，以紧凑表格呈现。
```
📦 更改
```
：按目录分组的已完成或计划更改；当树形结构能更清晰地显示路径归属时使用树形结构。
```
🧪 验证
```
：精确的命令、结果以及任何合理的跳过情况，以表格呈现。
```
⚠️ 阻碍因素与风险
```
：冲突、建议和无法识别的标志；为空时省略。

保持路径、命令、防护机制错误、符号链接目标和用户编写的内容精确且无修饰。省略空的细节，一旦选定目标达到完成标准即可停止。

References

参考资料

```
polish
```
: read
```
references/polish.md
```
.
```
create
```
: read
```
references/create-docs.md
```
.

```
polish
```
：阅读
```
references/polish.md
```
。
```
create
```
：阅读
```
references/create-docs.md
```
。