beautify-github-readme: a Codex skill that designs a repository README around its real proof

The problem is ordering, not missing information

The README states the diagnosis directly: most repositories already contain enough information, and the problem is usually the order. Visitors meet internal terminology, installation commands and directory trees before they learn what the project is for. That is a specific failure mode, and it is common in Python tooling, where the first screen of a README often shows a pip install line and a module tree.

The intended audience is repository maintainers who have a working project and a weak front page. The README lists real repositories that have gone through it, including oil-ppt, draw-ui, oil-icon, Selector, codex-dev-team, torqueDASH-Next, summertown and Wolfcha. Those are the maintainer's own projects plus a few others, and the list is presented as examples of the output, not as a user count. Nothing in the repository states how many people use the skill.

The framing matters because it rules out a whole class of tools. This is not a badge generator or a Markdown linter. It reads the repository first, identifies what the README calls the clearest value and proof, and only then decides how the page should look.

Three layers: content order, visual system, engineering constraints

In what the README calls whole-README mode, the skill works across three layers at once. The content layer removes repetition, moves proof forward, and replaces internal jargon with concrete outcomes. The visual layer derives color, typography, composition and project-native motifs before any hero is designed. The engineering layer keeps assets GitHub-safe, images accessible, commands copyable and body text searchable.

That third layer is where the design decisions get constrained. GitHub READMEs do not offer the layout freedom of a website, so the skill splits the visual and content work. SVG carries editable heroes, section transitions, comparisons, diagrams and identity. Hybrid composition combines deterministic SVG layout with optional AI-generated, background-removed subjects for characters, organic texture, complex materials and cinematic lighting. GIF handles approved motion, with the static SVG remaining the editable fallback. PNG and WebP handle screenshots, generated artwork and showcase walls. Markdown keeps explanations, commands, links, configuration and contribution details.

The stated goal is a page that feels designed without becoming one long image that nobody can search, copy or maintain. Motion is opt-in and is never generated by default, which is a deliberate limit rather than an oversight.

The repository ships four reference documents under skills/beautify-github-readme/references/: project-native-hero.md, svg-production.md, hybrid-svg-production.md and motion-production.md. Those files, not the README, are where the production guidance lives. If you want to judge the skill before running it, read those four first.

Installing the skill and running the first pass

The README does not document an install command, a package name or a version. There is no release to pin to, and the homepage field is empty. What the repository does show is a skills/ directory at the top level, and the topics list includes agent-skill and codex-skill, so the skill is consumed from a checkout rather than from a package index. Clone the repository and point your agent at the skill directory:

git clone https://github.com/oil-oil/beautify-github-readme.git
cd beautify-github-readme
ls skills/beautify-github-readme/references/

The listing should show project-native-hero.md, svg-production.md, hybrid-svg-production.md and motion-production.md. That confirms you have the guidance files the skill works against.

From there, the workflow is the one the README describes in its workflow diagram: understand the project, set the direction, structure the content, build the visuals, review the preview. The first pass is the understanding step, and it runs against the repository you want to rewrite, not against the skill repository. Run it from inside the target project so the agent reads the real code, tests and assets:

cd /path/to/your-project
ls

What you should get back is a proposed content order: what the project is, then proof, then method, then first use. The README's before-and-after diagram describes exactly this shift, from dense information with no clear entry point to a value, proof, method and first-use sequence. Review that order before letting the skill generate any SVG, because the visual direction is derived from the content order, not the other way round.

One thing to settle before you start: the README says the process keeps three promises, and the visible two are to use real project material and never invent capabilities. If your repository lacks a runnable example or a real screenshot, the skill has less to work with, and the output will lean harder on typography and layout.

Where it breaks down: thin repositories and spec-style READMEs

The skill reads the repository first. That is the mechanism and also the limitation. A repository with no runnable example, no real output and no screenshots gives it nothing to move forward as proof, so the result is a better-ordered page with weaker evidence behind it. The README is explicit that it will not invent capabilities, which means a thin repository produces a thin README, just a tidier one.

A second case is the README that is deliberately a specification. Projects that document wire formats, protocol versions or configuration keys in strict order are often read by people who jump straight to a section. Reordering value and proof to the top can push that reference material down the page. The skill is built for projects whose first screen is the problem, not for documents whose first screen is the contract.

There is also a cost question the repository does not answer. The README does not document rollback, and it does not describe how to diff or revert a generated pass. Since the output mixes Markdown edits with new SVG and possibly PNG or WebP assets, a maintainer who wants to compare versions should keep the original README under version control before running anything. Git itself is the only rollback path the repository implies.

Finally, the optional showcase list is worth reading carefully. The README says submitting your README to that list is completely optional, that the footer signature is appreciated but never required, and that submissions are subject to maintainer review. Nothing there changes the licence or adds an obligation.

How it differs from template-based README generators

The obvious alternative is a template generator: pick a layout, fill in the placeholders, get a consistent result. The difference is where the design decision happens. A template decides the layout before it knows anything about the project, so the same hero shape, the same badge row and the same section order get applied to a CLI, an icon set and a research repository alike.

beautify-github-readme inverts that. The README states that different projects should not receive the same template, and gives the reasoning: a CLI can use command rhythm and cursors, an icon system can use keylines and cutouts, a research repository can use coordinates, charts and evidence labels. The visual vocabulary is derived from the project's own material rather than selected from a menu.

That is a real trade-off, not a strict improvement. A template generator is predictable and fast, and two repositories built from the same template look like siblings, which some organisations want. This skill produces a project-specific result, which means more setup per repository and no guarantee that two of your projects will look related. The repository does not describe a shared theme system for keeping multiple projects consistent.

The four hero directions shown in the README make the point visually: a Kubernetes example with a black system layout and cluster relationship diagram, a PostgreSQL example with a deep blue editorial layout and relational tables, and Block World and Wolfcha as hybrid cases. The README says these do not share one house style. That is the intended behaviour.

Licence, maintenance and what an upgrade costs

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are included. That is a permissive licence with no copyleft obligation, and it means the SVGs and Markdown the skill helps you produce are not encumbered by it. This is a description of the licence text, not legal advice; if you are redistributing the skill inside a product, have someone check the notice requirements.

The repository is not archived, and the last push was on 2026-09-10. There are no releases, so there is no version number to track and no changelog to read. Upgrades therefore happen at the commit level: you pull the repository again and compare the skills/ directory against what you had. The four reference documents are the files most likely to change the output, so diff those first.

Because the skill is consumed as files rather than as an installed package, there is no dependency resolution step and no lockfile to maintain. The cost of an upgrade is the cost of re-reading four Markdown files and deciding whether to re-run a README pass. The cost of not upgrading is that the production guidance drifts from what your README was built against, which matters if you later regenerate the SVG assets.

Editorial conclusion

Adopt beautify-github-readme if your repository already works and the README is the weak link, and if you are comfortable running an agent skill against a checkout of the repo. Do not adopt it if you want a template you can fill in by hand, or if your README is a specification that must not be reordered. Before running it, verify two things: that your checkout is the one the skill will read, and that the reference files under skills/beautify-github-readme/references/ match the visual direction you want, because those four documents are what the output is built against.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. oil-oil/beautify-github-readme on GitHub
4. README