GitHub-ready multilingual README sets, forged from facts —
verified by a deterministic gate, never by self-assessment.

English | 한국어

readme-forge forges GitHub-ready multilingual README sets out of a target repository — mined from the repo's own facts, never invented. It produces an English canonical README.md, a Korean sibling (more languages on request) wired with a README-I18N selector, attribution and Korea-practical sponsorship blocks, an emil-tone SVG banner, and a deterministic gate report. It is an agent skill that ships the kind of README it writes.

What it does · Install · Usage · How it works · Verification gates · Attribution

What it does

• Facts or nothing. Every feature, number, install command, and sponsor handle must trace to repository evidence. If a fact cannot be mined, the skill asks once — then writes "to be declared" instead of guessing.
• A fixed anatomy. A 14-section spec from hero cluster to footer; sections without real content are dropped, never padded. Badges are capped at four, each a verifiable fact.
• Multilingual by construction. English canonical README.md plus BCP47 siblings; a marker-delimited language selector (<!-- README-I18N:START/END -->); translated headings get their GitHub-slug anchors rewritten.
• Korea-practical sponsoring. .github/FUNDING.yml across the full platform key set, plus a decision table born from a hard constraint: GitHub Sponsors payouts run through Stripe, which does not serve South Korea — so Toss, Ko-fi, Patreon, and Open Collective rails are wired as the practical stack.
• Attribution discipline. A three-piece registry pattern (machine-readable SSOT + public Markdown + human-readable HTML), strict license separation, and no-endorsement lines; CITATION.cff as an option for research-adjacent projects.
• Emil-tone banner. docs/assets/banner.svg — an ink card with a gold hairline frame and Georgia serif, one real stat line, readable on both GitHub themes.

Install

The distributable skill lives in skills/readme-forge/. Link it into your agent's skills directory:

git clone https://github.com/yelixir-dev/readme-gen.git
ln -s "$(pwd)/readme-gen/skills/readme-forge" ~/.agents/skills/readme-forge

Adapt ~/.agents/skills to your harness (e.g. ~/.claude/skills); a plain copy instead of a symlink works too. Start a new agent session and the skill's triggers are live.

Usage

Ask your agent, in English or Korean — “리드미 만들어줘”, “README 작성해줘”, “README 다국어로”, “generate a README”, “forge a readme”. Point it at the repository you are about to publish.

You receive the set: README.md + README.ko.md, docs/assets/banner.svg, .github/FUNDING.yml, and a gate report that must pass before delivery. The run against this very repository printed:

PASS: 2 files, 9 headings, 6 fence markers, 3 badges, 3 relative links

How it works

1. Mine. The repo's own facts first — AGENTS.md, SKILL.md, package manifests, docs/ — then code, then your statements. Anything still missing is asked exactly once.
2. English canonical. references/anatomy.md fixes the section order; the banner follows references/banner-emil.md.
3. Multilingual siblings. README.ko.md by default, further languages as BCP47 siblings on request, all per references/multilingual.md.
4. Wiring. Attribution registry links, sponsorship via references/sponsorship.md; if no LICENSE exists, the License section says "to be declared" and you get a pre-publication warning — never an invented license.
5. Gate. scripts/check_readme.py must exit 0. Preview simulation was discontinued in v0.2 — review documents are separate emil-tone artifacts, not GitHub replicas.

Verification gates

Check	Blocks delivery when
Consistency	fence counts, heading counts, badge URL sets, relative-link sets, or img src sets differ across variants
Anchors	any ](#…) link fails to resolve to a same-file GitHub slug (duplicate headings modeled with -1, -2 suffixes)
Selector	the README-I18N marker block is missing or duplicated, or a selector link target does not exist
Assets	a relative link or img src target is missing on disk
Required sections	the canonical README lacks a --require'd section (default: what-it-does, install, usage, license)
Funding	.github/FUNDING.yml uses a key outside the platform whitelist, or the YAML does not parse (when pyyaml is available)

Repository layout

├── skills/readme-forge/    the skill (SSOT; symlinked into ~/.agents/skills)
│   ├── SKILL.md                  contract — 4 principles + pipeline phases
│   ├── references/               anatomy · multilingual · attribution · sponsorship · banner-emil
│   ├── templates/                readme.skill.md (full) · readme.generic.md (minimal)
│   ├── scripts/check_readme.py   the deterministic gate (stdlib-only)
│   └── tests/                    unittest suite for the gate

Attribution

Conventions were adapted from public sources: the language-selector marker and the translation-preservation discipline from xixu-me/readme-i18n, section discipline from standard-readme, and FUNDING.yml keys plus heading-slug behavior from GitHub's documentation. No third-party licensed material is vendored in this repository.

Current limitations

• v0.2, young. The anatomy has been forged against few production repositories and may overfit agent-skill projects until more project types ship.
• English canonical only. Other canonical languages are out of scope; siblings follow BCP47 naming.
• Structure, not prose. The gate verifies structure, anchors, assets, and funding files — not writing quality; review remains a human pass over a separate review document.
• Decision tables age. The Korea sponsorship table reflects payout policies as of writing; verify rails at setup time.

License

Released under the MIT License.

---

readme-forge — READMEs that prove themselves.