Agent 技能中文汉化

要解决的问题

AI 编程工具里装满了插件，但很多技能的 description 仍然是英文。结果就是：搜索和触发靠英文关键词，可读性靠猜。你想用一个画流程图的技能，却不知道该输入 /mermaid 还是 “画流程图”；斜杠菜单里显示的是 kebab-case 英文名，完全看不出这个技能能做什么。

更麻烦的是，技能可能装在多个工具里：Claude Code、Codex、OpenCode、TRAE Work、OpenClaw、Cursor、Windsurf……每个工具对技能文件的路径、格式和校验规则都不一样。手工汉化一个文件不难，但要跨工具保持一致、回滚方便、不破坏机器可解析的字段，很容易出错。

这个技能把这件事变成一条可重复的流程：扫描、备份、翻译、校验、报告。

核心能力

按工具适配的扫描与写入规则。 技能内置一组适配器，分别对应 Claude Code、Codex、OpenCode、Antigravity、TRAE Work、OpenClaw，以及纯 Skill 平台（Cursor、Windsurf、WorkBuddy 等）。适配器负责告诉流程：扫描哪些路径、写入时有哪些限制、哪些字段不能动。跨工具的通用写入规则放在 references/zh-rules.md，术语统一靠 references/glossary.md。

扫描时按 frontmatter 分类，不盲目改写。 对每个技能文件读取 frontmatter 后，会分成几种情况：已有英文 description 的标记为待汉化；没有 description 但正文有内容的标记为待生成；没有内容、符号链接、或已中文占比超过一半的，分别跳过或需要确认。这样能避免把已经处理好的文件反复改动，也避免误碰结构不完整的文件。

翻译只动人类可读字段，正文默认不动。 对 Agent 文件尤其谨慎：正文是精心调校的 System Prompt，改动任何字符都可能改变行为模式。所以汉化只翻译 frontmatter 中面向人类的 description、when_to_use，正文保持原样，并在改完后逐字符比对确认。对普通 Skill，Markdown 正文里需要翻译的自然语言部分逐段处理，但代码块、路径、URL 一律不动。

扩写式中文，而不是逐字翻译。 翻译风格要求动词 + 对象 + 补充说明，并覆盖用户最可能说的几种说法。例如 生成 Mermaid 图表 | 画流程图、时序图、架构图、mermaid、diagram、chart。这样中文用户搜“画流程图”能触发，英文用户搜 mermaid 也能触发。

写入前自动备份，写入后逐项校验。 所有待汉化或待生成的文件会先复制到 ~/.claude/backup-i18n-{时间戳}/，保留原目录结构。--dry-run 和 --confirm 二选一，默认走 dry-run 预览。修改后立即检查：frontmatter 仍是合法 YAML、name 字段未变、工具名和权限规则未变、description 不超过 Codex 的 1024 字符限制。Agent 文件还要与备份逐字符比对，任何不一致都会从备份恢复。

可选的非破坏性 overlay 模式。 如果不想覆盖原 description，可以加 --overlay，改为新增 description_zh 字段。这样 marketplace 更新时不会直接覆盖中文，切换工具时也能回退到英文。代价是 Claude Code 不会自动识别 description_zh，实际触发仍依赖原英文描述。

除汉化外，还能扫描全量能力并更新 CLAUDE.md。 传入 scan 时，技能会按 scope 扫描各工具的 skills、agents、commands、MCP 配置，甚至检测本机可用的 CLI 工具，生成一份能力清单，并写入或替换 CLAUDE.md 中标记区间。清单行数超过 50 行时自动截断，每个工具最多保留 5 个名称。如果发现 agent 数量少于 5 个，还会根据 CLAUDE.md、会话记录、记忆文件和已装技能推断工作领域，推荐并下载人设文件。

适用边界与注意点

• 它处理的是元数据可读性，不是改写行为。 汉化不会重写 agent 正文，也不会改变技能的实际能力。
• 符号链接需要手动选择。 遇到符号链接时会提示：修改源文件会影响所有引用它的工具，但会破坏锁文件哈希校验；跳过则保持原样；断开链接并创建独立副本最安全，但需要额外磁盘空间。
• marketplace 来源的技能可能被覆盖。 若文件带有 _meta.json，汉化后仍可能在 marketplace 更新时被英文原版覆盖。技能会提示这一点，但继续执行汉化。
• 只支持适配器覆盖的工具。 目前包括 Claude Code、Codex、OpenCode、Antigravity、TRAE Work、OpenClaw，以及 Cursor、Windsurf、WorkBuddy 等纯 Skill 平台。未接入的工具不在处理范围内。
• agent 安装需要联网访问 GitHub Raw。 推荐流程会从 agency-agents-zh 仓库下载 .md，并按目标工具转换格式，例如 Codex 需要转成 TOML，OpenCode 需要加 mode: subagent 字段。

如果你的团队同时使用多个 AI 编程工具，并且希望技能列表里的描述能被中文用户看懂、被英文关键词触发，这个技能可以省下大量重复劳动。