oil-oil GitHub avatar

beautify-github-readme

oil-oil

A GitHub Skill that redesigns repository READMEs by understanding the project, restructuring content, and generating project-native visual assets without inventing capabilities.

Stars

1,339

7-day growth

No data

Forks

88

Open issues

1

License

MIT

Last updated

2026-07-27

AI repository intelligence
FR-AI / ANALYSIS

Why it is worth attention

It addresses the common problem of unclear READMEs by moving proof before jargon, separating visual identity (SVG) from usable Markdown, and already powering four public repositories with distinct visual languages.

Who it is for

  • Open-source maintainers wanting clearer landing pages
  • Developers who create frequent README updates
  • Project authors seeking consistent visual identity across repos
  • AI agent users who want automated but safe README improvements

Use cases

  • Redesign an entire README around the project's real value and proof
  • Generate only visual assets (SVG hero, diagrams, motion) without modifying text
  • Run a read-only audit for clarity, hierarchy, trust, and maintenance cost
  • Create a project-native hero that derives typography, color, and composition from the project itself

Strengths

  • Already used by four public repositories with different visual identities (oil-ppt, draw-ui, oil-icon, Selector, torqueDASH-Next)
  • Separates visual layer (SVG) from content (Markdown) so the README remains searchable and maintainable
  • Provides explicit whole-README and asset-only modes with local previews and no automatic commits
  • Includes a read-only audit feature that does not edit any files

Considerations

  • Requires installing a Skill via npx or an agent, adding a setup step
  • Output quality depends on the richness of the project's existing material—bare-minimum repos may yield limited improvements
  • The method emphasizes design decisions that may need iterative feedback when the project lacks clear identity

README quick start

English · 简体中文 · 日本語

These are not hypothetical templates. The method is already used by eight public repositories, each with its own visual language and content structure:

  • oil-ppt — presents the method, results, and first-use path for programmatic slide creation in one visual system.
  • draw-ui — uses real UI outputs to explain the path from a brief and reference images to HTML/CSS reconstruction.
  • oil-icon — uses real icon sets to explain style locking, batch generation, slicing, and transparent delivery.
  • Selector — puts page selection, structured context, and real output directly into the opening screen and examples.
  • codex-dev-team — uses a character-driven team map to explain how one main Codex thread delegates exploration, bounded implementation, and independent review to four custom agents.
  • torqueDASH-Next — uses a project-native SVG hero with OBD-II PID data and a real dashboard screenshot to explain a self-hosted vehicle telemetry dashboard.
  • summertown — uses a seaside-map hero and landmark showcase to introduce an interactive town map.
  • Wolfcha — combines SVG typography and an AI-generated character cutout to turn “play Werewolf solo” into a cinematic, project-native opening screen.

If this Skill helped you create a public README you are proud of, you are welcome to propose it for this list in a PR. This is completely optional: the footer signature is appreciated but never required, and showcase submissions remain subject to maintainer review.

Below are four independent hero directions. They do not share one house style; each derives its typography, color, composition, and proof from the project itself.

Block World shows a playful hybrid direction: SVG builds the pixel typography, grid, labels, and scene structure, while ImageGen and chroma-key removal supply the character that would be cumbersome to draw deterministically.

Wolfcha is a real hybrid case: ImageGen created the project-

Description

Design clear, theme-specific GitHub README homepages with SVG titles, real proof, and maintainable Markdown

Related repositories

Similar projects matched by category, topics, and programming language.

powerycy
Featured
powerycy GitHub avatar

goutoujunshi

An AI relationship coach that provides emotional support, relationship science, and actionable strategies through a multidisciplinary knowledge base.

Python
1,174
HezaoHezao
Featured
HezaoHezao GitHub avatar

poirot

Poirot is a deep research agent kernel with a middleware-first architecture, five-layer long-term memory, multi-agent orchestration, sandbox isolation, and a three-layer skill self-evolution system, backed by 2400+ tests.

AI & Machine LearningLarge Language Models
25
lopopolo
Featured
lopopolo GitHub avatar

harness-engineering

Harness Engineering is a methodology for improving coding agent outputs by carefully crafting the environment around them—providing curated context, tools, and executable constraints that encode an organization’s nonfunctional requirements and cumulative lessons.

AI & Machine LearningAI Agents
2,390