sync-readme
npx machina-cli add skill lbb00/ai-rules-sync/sync-readme --openclawSync README
Purpose
Keep the English (README.md) and Chinese (README_ZH.md) documentation in sync. When one is updated, this skill helps translate and synchronize changes to the other.
Instructions
-
Compare Both Files
- Read README.md and README_ZH.md
- Identify sections that differ
- Note new sections in either file
-
Determine Sync Direction
- If English was updated more recently: translate EN → ZH
- If Chinese was updated more recently: translate ZH → EN
- If unclear, ask user which is the source of truth
-
Translate Content
- Preserve all code blocks unchanged
- Translate prose sections accurately
- Keep technical terms consistent:
- "rules" → "规则"
- "commands" → "命令"
- "skills" → "技能"
- "agents" → "代理"
- "instructions" → "指令"
- "adapter" → "适配器"
- "symbolic link" → "软链接"
-
Preserve Structure
- Keep same heading hierarchy
- Maintain table formats
- Preserve all links and badges
- Keep code examples identical
-
Update Language Links
- Ensure language toggle links are present
- English:
[English](./README.md) | [中文](./README_ZH.md) - Chinese:
[English](./README.md) | [中文](./README_ZH.md)
-
Verify Completeness
- All sections present in both files
- All features documented in both
- Examples work in both versions
Translation Guidelines
Section Headers
| English | Chinese |
|---|---|
| Install | 安装 |
| Commands | 命令 |
| Architecture | 架构 |
| Tab Completion | Tab 补全 |
| Legacy compatibility | Legacy 兼容说明 |
| Supported Sync Types | 支持的同步类型 |
Common Phrases
| English | Chinese |
|---|---|
| Default mapping | 默认映射 |
| Source directory | 源目录 |
| Target directory | 目标目录 |
| Run this command | 运行此命令 |
| This command will | 该命令会 |
Output
After running this skill:
- Both README files contain identical information
- All features documented in both languages
- Formatting consistent across both files
Source
git clone https://github.com/lbb00/ai-rules-sync/blob/main/.claude/skills/sync-readme/SKILL.mdView on GitHub Overview
Automatically keep English README.md and Chinese README_ZH.md in sync to maintain parity. It translates changes from the source language to the target while preserving code blocks, structure, links and badges.
How This Skill Works
It compares README.md and README_ZH.md to identify differences and new sections. It then decides the sync direction based on which file was updated most recently; if unclear, it asks for the source of truth. It translates prose while preserving code blocks and known term mappings (rules -> 规则, commands -> 命令, skills -> 技能, agents -> 代理, instructions -> 指令, adapter -> 适配器, symbolic link -> 软链接) and preserves headings, tables and all links and code examples.
When to Use It
- You updated the English README and need a Chinese translation to stay in sync.
- A Chinese README has new content and must be mirrored in English.
- Launching a bilingual project with identical feature documentation.
- After a major release, both READMEs reflect new sections and commands.
- You want to ensure language toggle links are present and correct.
Quick Start
- Step 1: Read both README.md and README_ZH.md to identify diffs.
- Step 2: Determine which language was updated most recently and set the sync direction.
- Step 3: Translate prose, preserve code blocks and structure, update language links, and verify parity in both files.
Best Practices
- Check timestamps to choose the source of truth before translating.
- Preserve all code blocks and keep code examples identical.
- Apply the standard term mappings consistently across both files.
- Maintain the original heading hierarchy, tables, links and badges.
- Validate both READMEs render correctly and test all links and badges.
Example Use Cases
- An open-source project maintains bilingual READMEs and auto-syncs after PRs.
- A team translates updates in English and mirrors them to Chinese for a bilingual repo.
- After a major release, both READMEs reflect new sections and new commands in sync.
- Localization guidelines are enforced to unify translated terms across docs.
- Drift is resolved when English is updated more recently than the CN version.
