Redesign a GitHub README Around Its Real Project with beautify-github-readme

Most READMEs do not lack information — they lack order. beautify-github-readme, a 2k-star MIT agent skill published on the same GitHub account as oil-ui and oil-motion, starts from that diagnosis: visitors see internal terminology, installation commands, and directory trees before they understand what the project is for.

Why This Skill Matters

Per the README, the skill reads the real repository first, identifies the clearest value and proof, and only then decides how the page should look. In whole-README mode it works across three layers — content (remove repetition, move proof forward, replace internal jargon with concrete outcomes), visual system (derive color, typography, composition, and project-native motifs before designing the hero and supporting modules), and engineering (keep assets GitHub-safe, images accessible, commands copyable, and body text searchable). Different projects should not receive the same template: the README's examples are a CLI using command rhythm and cursors, an icon system using keylines and cutouts, and a research repository using coordinates, charts, and evidence labels.

The method separates the visual and content layers because GitHub READMEs lack a website's layout freedom. SVG handles editable heroes, section transitions, comparisons, diagrams, and identity; hybrid SVG composition combines deterministic SVG layout with optional AI-generated, background-removed subjects; GIF handles approved motion while the static SVG remains the editable fallback — and motion is opt-in, never generated by default; PNG/WebP handles screenshots, generated artwork, and complex showcase walls; Markdown handles explanations, commands, links, configuration, and contribution details. The README itself is a working example of the approach, and it lists eight repositories already using the skill.

Installation

npx skills add oil-oil/beautify-github-readme

Or ask your agent to install it:

Install this Skill: https://github.com/oil-oil/beautify-github-readme

Real Workflow: Whole README or Assets Only

The skill has two explicit modes. Whole README changes the reading order, copy hierarchy, proof, Markdown, and the complete visual system, and will not commit, push, or publish without approval. Asset-only produces a static SVG hero, section headers, workflow, badge, diagram, or an optional GitHub-safe GIF with SVG source, and will not edit README copy, order, image references, or links.

1. State the scope and the skill starts directly. If you only say "beautify this repository" or paste a URL, the agent asks which mode you want and, for asset-only, which assets.
2. For a full redesign, the README's prompt asks for a local preview first:

Use $beautify-github-readme to redesign this repository homepage around its real project theme.
Show me a local preview first and do not push anything.

3. For assets only, keep the README untouched:

Use $beautify-github-readme to keep the README unchanged and create one animated GIF hero with its SVG source.
Derive the style from the existing project and show me the rendered preview first.

4. Review the deliverables. Whole-README mode delivers a local preview, visual assets, and a README diff; asset-only mode delivers source assets, rendered previews, optional GIF derivatives, and embed snippets. Commits, pushes, PRs, and publishing always require explicit authorization, and in asset-only mode embedding the new assets requires a separate, explicit approval — reading a README for context does not grant permission to edit it.

A third, read-only request audits without touching anything:

Use $beautify-github-readme to audit this README for clarity, hierarchy, trust, and maintenance cost. Do not edit files.

Tips

• The reusable production guidance ships as reference files inside the skill: designing a project-native hero, writing GitHub-safe README SVGs, composing SVG with generated raster material, and producing GitHub-safe README motion.
• The README's hybrid examples (Block World, Wolfcha) show where AI-generated material fits: SVG keeps typography, grids, and composition precise, while ImageGen plus chroma-key removal supplies a character that would be cumbersome to draw deterministically.
• Markdown and SVG need no account or API key; per the README, generating PNG/WebP or using AI image generation requires the corresponding rendering and authorized generation tools.
• The process keeps three promises the README states outright: use real project material, never invent capabilities, and never publish without explicit approval — it will not fabricate stars, performance, users, or brand endorsements.

When Not to Use This

The README's three promises set the boundary: the skill uses real project material and never invents capabilities or fabricates stars, performance, users, or brand endorsements. And because motion and AI-generated raster material are opt-in and depend on tools outside the skill, a Markdown-and-SVG result is the documented baseline; anything beyond it needs your rendering and generation tooling in place.

See the leaderboard for more skills.