write-strict-readme

name	write-strict-readme
description	Create, revise, split, or audit README.md files for Guanyu Wang's research/code repositories. Use whenever a task mentions README, readme, documentation index, GitHub rendering, bilingual English/Chinese README pairs, README_zh.md, artifact navigation, figure/table/report links, reproducibility handoff, Markdown math rendering, or README cleanup/push readiness.

Write Strict README

Overview

Use this skill to produce README files that work on GitHub without repeated correction: English README.md as the primary page, complete Chinese README_zh.md mirror, right-aligned language switch links, clickable relative indexes, reproducibility evidence paths, figure/table guidance, and explicit claim boundaries.

Required Reference

Before editing README files, load references/readme-contract.md. It is the normative checklist for structure, bilingual split, GitHub links, math compatibility, evidence coverage, and final validation.

Core Workflow

1. Find every existing README.md and README_zh.md under the requested scope with both git ls-files '*README*.md' and rg --files --no-ignore -g 'README*.md'; broad .gitignore rules can hide tracked README files from normal rg --files.
2. Preserve content first:
   • If converting an existing README, create or update the same-folder README_zh.md before replacing README.md.
   • Do not delete existing claims, evidence paths, reports, figures, commands, risk notes, or cleanup notes; merge and reorganize them.
3. Make README.md the English primary page unless the user explicitly says otherwise.
4. Make README_zh.md a complete Chinese mirror, not a stub and not a partial summary.
5. Add GitHub-safe right-aligned language switch links to both files.
6. Convert all important indexes and evidence tables to clickable relative Markdown links.
7. Fix Markdown rendering hazards, especially unsupported operator-name math macros.
8. Run the language-balance gate and final checks in references/readme-contract.md before saying the README work is complete.

Non-Negotiables

• README files are navigation pages, not changelog dumps.
• English README.md must not contain Chinese body text if the user asked for a pure English main README.
• Chinese README_zh.md must keep the actual technical substance: evidence, commands, figures, risks, missing outputs, and claim boundaries.
• A README pair is incomplete if only the root directory is handled while subfolder READMEs remain unsplit.
• A GitHub index is incomplete if paths appear only as code text and not as clickable relative links.
• A figure package is incomplete if it does not tell collaborators which PNG/PDF/SVG files exist, which are tracked, which are ignored, and how to interpret risky curves.
• Public README files must not expose local absolute paths, provider/vendor names, assistant-brand names, or app-specific environment details unless the repository is explicitly about that integration; use relative links and generic placeholders.
• Chinese README_zh.md may use bilingual technical terms, filenames, and commands, but must not contain long English-only paragraphs or English-only table rows. English README.md must not contain long Chinese body text unless explicitly requested.

Validation Commands

Use PowerShell-compatible commands in Windows workspaces:

git ls-files '*README*.md'
rg --files --no-ignore -g 'README*.md'
git diff --check
$badMath = 'operator' + 'name|' + 'The following macros' + ' are not allowed'
rg -n $badMath (git ls-files '*README*.md')
$publicLeak = 'C:' + '\\\\Users|\\.' + 'co' + 'dex|Cla' + 'ude|Anth' + 'ropic|Chat' + 'GPT|Open' + 'AI|Co' + 'dex'
rg -n $publicLeak (git ls-files '*README*.md')
python <skill-folder>\scripts\audit_readme_language_balance.py README.md README_zh.md

For the final rg check, exit code 1 with no output means a clean pass because no forbidden macro was found.

Also check all English primary READMEs for accidental Chinese body text. Language-switch links may use Chinese; prefer avoiding Chinese characters in English primary files when the user asks for pure English.