A Claude Code skill that transforms plain README files
into stunning, website-like experiences

How It Works  •  Features  •  Install  •  Techniques  •  Examples  •  Website

 The Difference

 How It Works

 Features

 Install

Manual installation

git clone https://github.com/oxgeneral/PerfectReadme.git
mkdir -p ~/.claude/skills/perfect-readme
cp PerfectReadme/skills/perfect-readme/SKILL.md ~/.claude/skills/perfect-readme/

 Techniques

The skill builds READMEs as component-based landing pages using SVG blocks assembled in markdown.

Pure SVG + SMIL Each section is a standalone .svg with native SVG elements and SMIL <animate> tags. Gradients, filters, patterns, animations — all survive GitHub's camo proxy. No <foreignObject>, no CSS, no JavaScript.	Dark / Light Themes Every SVG component has a dark and light variant. The <picture> element with prefers-color-scheme media queries switches automatically based on the user's system theme.
Component Assembly SVG files are visual building blocks — hero banners, feature grids, timelines, install cards, dividers. Markdown text and HTML tables provide structure between blocks.	Landing Page in README The result is a README that looks and feels like a designed landing page — with visual hierarchy, color, motion, and polish — all within GitHub's rendering constraints.

 Examples

Usage

Once installed, just ask Claude Code:

Create a README for my project

/perfect-readme

Make a stunning GitHub profile README

The skill analyzes your project, chooses an aesthetic direction, generates SVG assets with dark/light variants, and assembles everything into a production-ready README.

What GitHub allows & strips

Allowed HTML: div, table, details, summary, picture, source, img, a, br, hr, kbd, sup, sub, code, pre, blockquote, p, span, h1–h6, ul, ol, li, dl, dt, dd, figure, figcaption, b, strong, i, em, del, ins, mark, small

Allowed attributes: href, src, alt, width, height, align, valign, colspan, rowspan, open, srcset, media, type

Stripped: style, class, id, <script>, <iframe>, <form>, <style>, <link>, <foreignObject>, all event handlers, inline SVG

SVG via <img> — what survives: native SVG elements, SMIL <animate>, <linearGradient>, <pattern>, <filter>, <feGaussianBlur>

SVG via <img> — what's stripped: <foreignObject>, <style>, CSS @keyframes, @import, JavaScript, :hover

Project structure

PerfectReadme/
├── .claude-plugin/
│   └── plugin.json              # Plugin metadata
├── skills/
│   └── perfect-readme/
│       └── SKILL.md              # Skill definition
├── assets/
│   ├── banner-dark.svg           # Hero banner (dark)
│   ├── banner-light.svg          # Hero banner (light)
│   ├── features-dark.svg         # Feature cards (dark)
│   ├── features-light.svg        # Feature cards (light)
│   ├── steps-dark.svg            # Workflow timeline (dark)
│   ├── steps-light.svg           # Workflow timeline (light)
│   ├── install-dark.svg          # Install command (dark)
│   ├── install-light.svg         # Install command (light)
│   ├── before-after.svg          # Comparison visual
│   ├── divider-dark.svg          # Section divider (dark)
│   └── divider-light.svg         # Section divider (light)
├── index.html                    # Landing page (GitHub Pages)
├── LICENSE
└── README.md                     # ← You are here

View Landing Page →

_{This README is a live demo — built entirely from SVG components assembled in markdown.
MIT © 2026 Aleksandr Fefelov}