README 4-file synchronization procedure for the oss-docs harness: Korean README.ko.md as primary source, en/ja/zh derivation, the shared language-switcher header contract, section-order parity checklist, and the manual verification recipe (no linter exists for READMEs). Loaded by the content-author and locale-translator specialists for any README work.
Start a fresh conversation. Replace the highlighted placeholders.
Use hns-oss-docs-readme-sync to update [README change] in README.ko.md and derive minimal synchronized English, Japanese, and Chinese changes, preserving required verbatim content and completing the documented manual parity and rendering verification.
Required inputs
[README change]
User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗
SKILL.md
name: hns-oss-docs-readme-syncdescription: > README 4-file synchronization procedure for the oss-docs harness: Korean README.ko.md as primary source, en/ja/zh derivation, the shared language-switcher header contract, section-order parity checklist, and the manual verification recipe (no linter exists for READMEs). Loaded by the content-author and locale-translator specialists for any README work.allowed-tools: Read, Grep, Glob, Bashuser-invocable: falsemetadata: version: "2.0.0" category: "harness" status: "active" updated: "2026-08-17" tags: "oss-docs,readme,4-locale,translation,parity"
README 4-File Sync Procedure
The GitHub-facing README set is 4 files at the repo root:
File
Locale
Role
README.ko.md
ko
canonical / primary — author here first
README.md
en
derived
README.ja.md
ja
derived
README.zh.md
zh
derived
Chain history: the canonical locale was English until 2026-08-17, when
card t47 promoted the ko new-skeleton (feature-oriented section structure)
to canonical per the operator decision — aligning the README chain with the
docs-site chain, which was already ko-canonical. The former en-skeleton
redesign reference (.moai/reports/readme-docs-redesign-20260713.md) is
superseded by the ko skeleton and kept as history only.
Procedure
Author the change in README.ko.md (Korean) only. Respect the
canonical ko section skeleton; keep the file length in the range of the
current set.
Derive en, ja, zh — same PR, one derived file per translator worker.
Translate the changed sections minimally; do not rewrite untouched prose.
Preserve verbatim across all 4 files: code blocks, command names,
badges, version strings, file paths, tables' structure, Mermaid direction,
and the switcher header (below).
Verify parity (checklist below) before returning.
Language-switcher header contract [HARD]
All 4 files share the same switcher header near the top, linking the sibling
files with the label set exactly:
English · 한국어 · 日本語 · 中文
The current file's own label renders as plain text; the other 3 are links
to the sibling README files.
Never reorder, drop, or re-label the 4 entries.
Section-order parity checklist
grep -c '^## ' README.md README.ko.md README.ja.md README.zh.md —
identical H2 counts across the 4 files.
H2 section ORDER matches ko (compare grep '^## ' output order).
H3 counts per section match for sections you touched.
Table row counts match in touched sections.
Code-block count matches (```` grep -c '^```' ```` is even and equal).
Switcher header present and correct in all 4.
URL blacklist clean: grep -n 'docs\.moai-ai\.dev\|adk\.moai\.com\|adk\.moai\.kr' README*.md → no matches.
Manual verification recipe
No linter exists for the README set — verification is the manual recipe above
plus rendering sanity: preview the markdown (GitHub-flavored) for the touched
sections and confirm Mermaid blocks declare TD/TB only. The runnable
docs-site checks live in Skill("hns-oss-docs-verify"); the README-specific
checks are the greps above.
Anti-patterns
Anti-pattern
Correct approach
Editing README.md first "because GitHub is English-facing"
README canonical is ko — author README.ko.md, then derive
Re-authoring an entire derived file for a 3-line canonical change