agent-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Config

Agent配置

Purpose

用途

A repository's agent layer is one document read by many agents under different filenames. This skill establishes that layout and then keeps the document honest:

Init — one real instruction file at the repo root, every other host filename a relative symlink pointing at it.
Check — find documented commands, paths, directory structures, and counts that have drifted from the actual repo.

It never seeds an ambient rules directory. Code-shaped conventions are applied on demand by

code-cleanup

and the

audit/

skills; only the comment block below is cheap enough to live in always-loaded instructions.

仓库的Agent层是一个可被多个不同文件名的Agent读取的文档。本Skill用于建立该布局并确保文档的准确性：

初始化——在仓库根目录创建一个真实的指令文件，其他所有宿主文件名均为指向该文件的相对符号链接。
检查——找出文档中记录的命令、路径、目录结构和数量与实际仓库不符的漂移情况。

本Skill不会自动创建环境规则目录。代码类规范由

code-cleanup

和

audit/

类Skill按需应用；只有下方的注释块足够轻量化，可常驻于加载的指令中。

Asking the User

询问用户

Every question in this skill is written as

AskUserQuestion

options. Use that tool where the host offers it, or the host's nearest structured-choice equivalent. Where the host has neither, ask the same question in normal chat as a numbered list of 2–5 options — recommended first, one short line of description each — and wait for the user to reply with a number.

本Skill中的所有问题均以

AskUserQuestion

选项形式编写。若宿主支持该工具则直接使用，或使用宿主最接近的结构化选择等效工具。若两者均不支持，则以普通聊天形式提出问题，列出2-5个带编号的选项——首选项为推荐项，每个选项配一行简短描述——等待用户回复编号。

Arguments

参数

Argument	Behavior
(none)	Inspect, report, then ask what to do
`init`	Establish the layout: instruction file, symlinks, comment block
`check`	Drift report only — never modify anything
`apply`	Report drift and apply the fixable findings without re-confirming each

init

runs steps 1-4 and 7.

check

runs steps 1, 5.

apply

runs steps 1, 5-7. With no argument, run steps 1 and 5, then ask which half the user wants.

参数	行为说明
(无)	检查、报告，然后询问用户操作选择
`init`	建立布局：指令文件、符号链接、注释块
`check`	仅生成漂移报告——绝不修改任何内容
`apply`	报告漂移情况并应用可修复的结果，无需逐一确认

init

执行步骤1-4和7。

check

执行步骤1、5。

apply

执行步骤1、5-7。无参数时，执行步骤1和5，然后询问用户选择哪部分操作。

Requirements

依赖要求

The bundled script needs only

bash

ln

, and

readlink

— no external dependency. The drift check reads

package.json

with

jq

; without

jq

, parse it with

grep

sed

and say that command detection is best-effort. Gradle and Make task names come from

gradle tasks --quiet

and

make -qp

, which fall outside

allowed-tools

and will prompt — both are read-only, so approve them or skip the Commands category and say so in the report.

捆绑脚本仅需要

bash

、

ln

和

readlink

——无外部依赖。漂移检查使用

jq

读取

package.json

；若无

jq

，则使用

grep

sed

解析，并说明命令检测为尽力而为。Gradle和Make任务名称来自

gradle tasks --quiet

和

make -qp

，这两个命令不在

allowed-tools

范围内，会触发提示——两者均为只读操作，可批准执行或跳过命令类别并在报告中说明。

Auto-Activation

自动激活

Trigger phrases live in

when_to_use

. When activating on your own initiative rather than on a request — right after build scripts, directory names, tooling, or documented counts changed — always run

check

first and never apply without showing the report.

触发短语位于

when_to_use

中。当自行主动激活而非响应请求时——例如构建脚本、目录名称、工具或文档记录的数量变更后——务必先运行

check

，且未展示报告前绝不执行应用操作。

Canonical Layout

标准布局

One real file; everything else is a relative symlink to it.

Path	Read by	Required
`CLAUDE.md`	Claude Code	canonical
`AGENTS.md`	Codex, OpenCode, pi, and other agents on the AGENTS.md convention	yes
`GEMINI.md`	Gemini CLI	opt-in
`.github/copilot-instructions.md`	GitHub Copilot	opt-in

CLAUDE.md

is the default canonical file because it is the one filename no other host claims, which keeps the symlink direction unambiguous. If the repo already has a real
AGENTS.md
and no
CLAUDE.md
, leave that direction alone and link

CLAUDE.md

at it instead — flipping an existing arrangement churns history for nothing.

Symlinks, never copies. Two copies drift the moment one is edited, and no agent will tell you which one it read.

一个真实文件；其余所有均为指向它的相对符号链接。

路径	读取方	必填状态
`CLAUDE.md`	Claude Code	标准默认
`AGENTS.md`	Codex、OpenCode、pi及其他遵循AGENTS.md规范的Agent	是
`GEMINI.md`	Gemini CLI	可选加入
`.github/copilot-instructions.md`	GitHub Copilot	可选加入

CLAUDE.md

是默认的标准文件，因为没有其他宿主使用该文件名，可确保符号链接方向明确。若仓库已存在真实的
AGENTS.md
且无
CLAUDE.md
，则保留现有结构，转而将

CLAUDE.md

链接到它——翻转现有安排只会无意义地增加历史变更。

使用符号链接，绝不使用副本。两个副本从编辑其中一个的那一刻起就会出现漂移，且没有Agent会告知你它读取的是哪一个。

Workflow

工作流程

1. Inspect before writing anything

1. 写入前先检查

bash

bash <skill-dir>/scripts/agent-config.sh status

Exit codes:

consistent,

no canonical file (or two competing ones),

drift found.

Also note whether the repo is a git repository, what build system it uses, and whether an instruction file already carries real content. Report present / missing / drifted before proposing a single edit.

bash

bash <skill-dir>/scripts/agent-config.sh status

退出码：

表示一致，

表示无标准文件（或存在两个冲突文件），

表示发现漂移。

同时记录仓库是否为git仓库、使用的构建系统，以及指令文件是否已包含真实内容。在提议任何编辑前，先报告当前状态：存在/缺失/漂移。

2. Establish the instruction file

2. 创建指令文件

Missing — draft a minimal file from
```
assets/instructions-skeleton.md
```
, scoped to what this repo actually is. Fill it from evidence: the build file, the directory layout, the existing README. Delete every skeleton section the repo does not need. A short accurate file beats a complete-looking one.
Exists — leave the prose alone. It is the author's, and the built-in
```
/init
```
already covers writing one from scratch. Move to step 3.

Never write to

~/.claude/CLAUDE.md

~/.codex/AGENTS.md

, or any other user-level file.

缺失——从
```
assets/instructions-skeleton.md
```
生成最小化文件，范围限定为仓库实际需求。根据现有信息填充：构建文件、目录布局、现有README。删除仓库不需要的所有骨架章节。简短准确的文件优于看似完整的文件。
已存在——保留原有内容。内容属于作者，内置的
```
/init
```
已涵盖从头创建文件的场景。直接进入步骤3。

绝不写入

~/.claude/CLAUDE.md

、

~/.codex/AGENTS.md

或任何其他用户级文件。

3. Wire the symlinks

3. 配置符号链接

bash

bash <skill-dir>/scripts/agent-config.sh link AGENTS.md --dry-run
bash <skill-dir>/scripts/agent-config.sh link AGENTS.md

Add

GEMINI.md

.github/copilot-instructions.md

only when the user says the repo is used with those agents. Each unused link is one more file to explain.

Flags:

--canonical <file>

picks the real file explicitly,

--force

moves a conflicting regular file to

<name>.bak

first. Without

--force

the script refuses to touch a regular file and tells you to merge it by hand — that is the safe default, since such a file usually holds instructions someone wrote.

If the script reports both
CLAUDE.md
and
AGENTS.md
are regular files, stop and ask which is authoritative. Then merge the other into it and re-run with

--canonical

bash

bash <skill-dir>/scripts/agent-config.sh link AGENTS.md --dry-run
bash <skill-dir>/scripts/agent-config.sh link AGENTS.md

仅当用户表示仓库会与这些Agent配合使用时，才添加

GEMINI.md

或

.github/copilot-instructions.md

。每个未使用的链接都需要额外解释。

参数：

--canonical <file>

明确指定真实文件，

--force

先将冲突的常规文件移动到

<name>.bak

。若无

--force

，脚本会拒绝修改常规文件并提示手动合并——这是安全默认，因为此类文件通常包含有人编写的指令。

若脚本报告**

CLAUDE.md

和

AGENTS.md

均为常规文件**，请停止操作并询问哪个是权威文件。然后将另一个文件合并到权威文件中，再使用

--canonical

重新运行脚本。

4. Add the comment block

4. 添加注释块

Insert

assets/comments.md

into the instruction file verbatim, as its own

## Comments

section, if and only if:

the repo has source files using
```
//
```
line comments (or the block is adapted to the language's line-comment marker), and
the file does not already document comment conventions.

If it already has a comment section, report the difference and let the user decide. Do not merge two opinionated blocks.

This block is the one ambient rule that survived: comment prefixes are a local convention a model cannot infer, and they are worth a handful of lines in every session.

仅当满足以下条件时，将

assets/comments.md

原样插入指令文件，作为独立的

## 注释

章节：

仓库中的源文件使用
```
//
```
行注释（或已适配为对应语言的行注释标记），并且
文件尚未记录注释规范。

若文件已有注释章节，报告差异并由用户决定。不要合并两个带有主观观点的块。

此块是唯一保留的环境规则：注释前缀是模型无法推断的本地规范，值得在每次会话中占用几行内容。

5. Run the drift check

5. 运行漂移检查

Read

references/drift-checks.md

and follow it. In short: parse the file into sections, keep only the ones making structural claims, collect the matching ground truth, classify each finding, report grouped by section with line numbers.

Stop after the report when the mode is

check

阅读

references/drift-checks.md

并遵循其步骤。简而言之：将文件解析为章节，仅保留包含结构声明的章节，收集匹配的实际情况，对每个发现进行分类，按章节分组并附带行号进行报告。

若为

check

模式，报告后停止操作。

6. Apply

6. 应用修复

Apply only

STALE

COUNT_MISMATCH

, and

PATH_MISSING

findings, plus

RENAMED

ones the user confirmed.

INFORMATIONAL

findings are reported and never applied — deciding what deserves documenting belongs to the author.

Edits are surgical. Change the reference, not the surrounding prose.

仅应用

STALE

、

COUNT_MISMATCH

和

PATH_MISSING

类型的发现，以及用户确认的

RENAMED

类型发现。

INFORMATIONAL

类型发现仅报告绝不应用——决定哪些内容值得记录属于作者的职责。

编辑需精准。仅修改引用内容，不改动周围文本。

7. Verify

7. 验证

Re-run

status

, then

git status

and

git diff

so the user sees exactly what changed. A new symlink shows up in

git diff

as a mode

entry — that is correct, not a mistake.

重新运行

status

，然后运行

git status

和

git diff

，让用户清楚看到所有变更。新的符号链接在

git diff

中会显示为模式

的条目——这是正确的，并非错误。

Adjacent Skills

关联Skill

```
editor-config
```
owns
```
.zed
```
/
```
.vscode
```
and is a separate decision — mention it as a follow-up when this skill has just initialized a repo, but do not run it implicitly.
```
repo-hardening
```
owns GitHub-side settings. Unrelated to the instruction layer.
```
skill-audit
```
,
```
ci-audit
```
, and the rest of
```
audit/
```
own quality judgments. This skill only checks factual agreement between the instruction file and the repo.

```
editor-config
```
负责
```
.zed
```
/
```
.vscode
```
相关配置，是独立决策——当本Skill刚初始化仓库时可作为后续操作提及，但不要隐式运行。
```
repo-hardening
```
负责GitHub端设置。与指令层无关。
```
skill-audit
```
、
```
ci-audit
```
及其他
```
audit/
```
类Skill负责质量判断。本Skill仅检查指令文件与仓库之间的事实一致性。

Edge Cases

边缘情况

No instruction file and no
init
intent. In
```
check
```
mode, report that there is nothing to check and offer
```
init
```
. Do not create a file in check mode.
Non-git directory. The layout still works; skip the
```
git status
```
verification and say so.
AGENTS.md
is a copy, not a link. The common failure mode. Diff it against the canonical file first: if they agree, replace it with a symlink; if not, the divergence is content someone wrote — show the diff and ask before collapsing it.
A host that reads a directory, not a file.
```
.cursor/rules/
```
,
```
.claude/rules/
```
, and friends are out of scope. Report them if present, leave them untouched.
Symlinks on Windows checkouts. A repo cloned without symlink support materializes
```
AGENTS.md
```
as a text file containing the target path. If a one-line file whose content is a path shows up, that is the cause — say so instead of treating it as a duplicate.
Monorepos. This skill handles the repo root. Package-level instruction files are the author's business.

无指令文件且无初始化意图。在
```
check
```
模式下，报告无可检查内容并提供初始化选项。不要在check模式下创建文件。
非git目录。布局仍然有效；跳过
```
git status
```
验证并说明情况。
AGENTS.md
是副本而非链接。常见故障模式。先对比其与标准文件的差异：若内容一致，替换为符号链接；若不一致，说明差异是有人编写的内容——展示差异并在合并前询问用户。
读取目录而非文件的宿主。
```
.cursor/rules/
```
、
```
.claude/rules/
```
等不在范围内。若存在则报告，但不修改。
Windows检出中的符号链接。未开启符号链接支持克隆的仓库会将
```
AGENTS.md
```
生成为包含目标路径的文本文件。若出现内容为路径的单行文件，需说明原因而非视为重复文件。
单体仓库。本Skill仅处理仓库根目录。包级指令文件由作者自行处理。