Claude Code Skill

PerfectReadme

Transform plain README files into stunning, website-like experiences that make people stop scrolling

Install Skill GitHub

The Difference

Before & After

Drag the slider to see the transformation from a plain README to a PerfectReadme.

Before

my-project

A tool for doing things. It works pretty well.

npm install my-project

Usage

Import the package and call the function.

const result = doThing(options);

Features

  • Feature one
  • Feature two
  • Feature three

License

MIT

After
my-project
v2.1.0 MIT BUILD PASSING TypeScript
Features • Install • Usage • API • License
←→

Capabilities

Everything your README needs

The skill knows exactly what GitHub allows and what it strips, using only techniques that work in production.

Animated SVG Banners

Pure SVG with SMIL animations that survive GitHub's proxy. Gradient shimmer, floating glow orbs, pulsing lines — all auto-playing without JavaScript.

SMIL <animate>

Dark & Light Themes

Every visual element supports both themes via the <picture> element with prefers-color-scheme. Two SVGs per asset, zero JavaScript.

<picture> + media query

Multi-Column Layouts

HTML tables with width, align, and valign attributes create structured layouts. Feature grids, side-by-side comparisons, organized content.

<table> layouts

Bold Design Philosophy

Adapted from the frontend-design skill. Every README gets a unique aesthetic direction — not a template. Color palettes matched to the project's domain.

frontend-design DNA

Workflow

Three steps to a stunning README

The skill handles everything — from analyzing your project to generating production-ready assets.

1

Analyze

Reads your project's code, dependencies, and purpose. Understands what needs to be communicated.

2

Design

Chooses a bold aesthetic direction — typography, palette, animations — tailored to your project's domain.

3

Generate

Produces README.md, animated SVG banners, theme variants, and all assets. Ready to commit and push.

In Action

Watch it work

A real generation session — from prompt to finished README with assets.

claude — ~/my-project
$ Create a stunning README for this project

# Analyzing project structure...
Found: package.json, src/, TypeScript, React
Project type: Frontend library

# Choosing aesthetic direction...
Tone: refined-technical
Palette: electric blue + warm amber
Typography: Space Grotesk + JetBrains Mono

# Generating assets...
✓ assets/banner-dark.svg — animated hero banner
✓ assets/banner-light.svg — light theme variant
✓ assets/divider.svg — gradient section divider

# Building README.md...
✓ README.md — 6 sections, 2-column layout, 3 accordions

Done. README + 3 assets ready to push.

Get Started

Install in seconds

Choose your preferred installation method. The skill is available immediately in your next Claude Code session.

claude plugin add --from-github oxgeneral/PerfectReadme

Installs as a Claude Code plugin. The skill will auto-activate when you ask to create or redesign a README.

mkdir -p ~/.claude/skills/perfect-readme
cp skills/perfect-readme/SKILL.md ~/.claude/skills/perfect-readme/

Clone the repo first, then copy the skill file manually. Available in your next Claude Code session.