中英文 Markdown 同步（*-zh.md ↔ *.md）

适用场景

• 仓库里成对出现：xx.md（英文或主语言）与 xx-zh.md（中文）。
• 用户改了一边、要求另一边跟上，或显式要求「中英文同步」「对齐两个文档」。

若命名不同（例如 README.zh.md），以用户指明的路径为准；默认按下节约定识别。

文件命名约定（默认）

配对规则：去掉 -zh 后缀（在扩展名之前）即为主文件；例如 concatagents/README-zh.md ↔ concatagents/README.md。

若只有一侧文件，先向用户确认另一侧路径或是否新建。

同步原则

1. 结构优先：标题层级（#…###）、列表块、代码块边界、表格行列数应对齐；中文侧章节顺序与主文一致，便于对照。
2. 语义一致：同一小节叙述同一主题；新增/删除/重命名章节时两侧同步增删改。
3. 代码与命令：代码块、CLI 命令、路径、URL、配置键名保持与主文一致（勿翻译标识符）；仅翻译说明性文字与注释（若中文侧需要注释）。
4. 外链：中文侧外链可与主文相同；若主文为英文文档链接，中文侧可改为官方中文版（存在且稳定时），否则保留原链接并在括号内说明。
5. 语言切换链接（双向）：主文与 -zh.md 在文档顶部互相链接，便于读者切换语言（见下节）。
6. Frontmatter：若存在 YAML frontmatter，键保持一致；description 等可分别为英文/中文值。
7. 不臆造事实：主文未出现的技术细节不要仅在中文侧编造；若一侧有「待办」或占位，两侧用等价标记标出。

语言切换链接（*-zh.md ↔ *.md）

同步或新建双语文档对时，两侧都应在标题下方第一块内容加入指向对端的相对链接；缺则补、错则改，已有且正确则保留。

放置位置

• 紧跟 # 标题 之后、正文第一段之前；若已有简介段落，链接放在简介段落之前。
• 两侧链接行位置应对齐（都在标题后第一行），不要一侧在页首、另一侧在页尾。

链接写法（默认同目录）

• 使用相对路径（与文档同目录时只写文件名）；子目录文档按实际路径写，例如 [中文](../README-zh.md)。
• 链接文字：英文侧用 中文 或 Read in Chinese；中文侧用 English 或 阅读英文版。同一仓库内风格保持一致。
• 可选格式：单独一行，或 [English](README.md) \| [中文](README-zh.md) 放在英文侧；中文侧镜像为 [English](README.md) \| [中文](README-zh.md)（顺序可固定为 English 在前）。
• 不要链到错误配对（如 guide.md 链到 other-zh.md）；重命名文件后同步更新两侧链接。
• 语言切换链接仅指向配对文档，与正文外链、锚点链接分开；勿把 GitHub raw URL 或绝对仓库 URL 写进同仓相对文档（除非用户明确要求）。

示例

README.md（英文）

# My Project

[中文](README-zh.md)

Local HTTP shim for ...

README-zh.md（中文）

# My Project

[English](README.md)

面向 Claude Code 的本地 HTTP 代理 ...

推荐工作流（Agent）

1. 定位配对：根据用户给出的文件或 glob，解析出 xx.md 与 xx-zh.md。
2. 做结构 diff：比对标题大纲与主要块（段落 / 列表 / 代码 / 表格）；列出「仅一侧存在」的块。
3. 定主从：用户指定以哪边为准；未指定时以本次编辑所改文件为准，另一份跟进；若两边都大改，先合并主文再翻译/改写中文。
4. 改稿：先更新主文（若需要），再按结构逐节更新 -zh.md（或反向），避免遗漏孤立段落。
5. 补语言链接：确认两侧标题下均有指向对端的相对链接；新建 -zh.md 或重命名后必须同步更新。
6. 自检：再次比对标题列表长度与顺序；检查代码块语言标签与内容是否一致；内部链接锚点（若有）是否仍有效；语言切换链接是否双向可达。

验收清单（完成前勾选）

• 两侧一级标题数量与顺序一致（或刻意差异已用注释说明）。
• 无「主文已删、中文仍保留」的过期整节（除非用户要求保留历史说明）。
• 代码块、命令、JSON/YAML 片段与主文一致。
• 英文文档顶部有指向 -zh.md 的链接；中文文档顶部有指向主文的链接；路径与配对文件名正确。
• 未在答复中泄露密钥或隐私；文档内敏感示例已脱敏。

与 verbatim 用户文案的关系

若用户在任务里粘贴了必须逐字使用的段落（中英任一），将该段原样写入目标文件，不转述、不润色、不调换语序；其余部分仍按上表原则同步。

可选延伸阅读

若单文件过长，可将完整术语表或长附录拆到同目录 reference.md，两语言各一份或共享一份，并在两份主文档中链接；本 skill 不强制拆分。