animated-readme

animated-readme

Turn your README into a demo people watch.

A Claude Code skill. Claude reads your project, writes README copy a visitor gets in ten seconds, and renders animated GIFs that show what it does. Same input, same GIF, every time. Nothing is pushed until you approve it.

Sound familiar?

• The first screen of your README is install steps. A visitor still doesn't know what the project does.
• Not one image shows it working, or the one screen recording you have is three versions old.
• Re-recording the demo means setting everything up again and clicking through it by hand.
• The tagline reads "a composable, extensible framework for..." and means nothing to the person you built it for.
• Screen readers get "demo.gif" and nothing else.

Who it is for

A good fit if you maintain a project on GitHub, use Claude Code, and want a README that shows the thing working, without opening a video editor.

Not for you if you need a real screen recording of your app with live data. This renders animated illustrations from HTML. For a real recording, script your app with Playwright and keep the same record_html.py approach for the frames.

Before and after

How it works

1. It reads your project first. README, docs, code, changelog. Every claim in the new copy has to point at something in the repo.
2. It writes the copy to a short writing guide: problem first, plain words, no hype words, no em-dashes.
3. It fills three scene templates (hero, before and after, how it works) through one file, readme-scenes.json. The copy lives there, not in the HTML.
4. It renders the GIFs frame by frame: every animation is paused and seeked to each frame, then screenshotted. No screen recording, so the same input always gives the same GIF. It warns when a GIF goes over 4 MB, and writes the alt text next to each image line.

You review the README and the GIFs. Nothing is committed or pushed until you say so.

Examples

Each has a hero, a before and after, and a how it works GIF, plus real recordings of the tool working.

Quick start

See it render this README's own GIFs. You need Python 3.9+ and no account.

git clone https://github.com/BrianArfi/animated-readme
cd animated-readme
pip install playwright pillow && python -m playwright install chromium
python scripts/render.py

The GIFs land in docs/. ffmpeg on your PATH gives smaller, sharper GIFs; without it, Pillow builds them.

Use it on your own project

cd your-project
mkdir -p .claude/skills .claude/commands
cp -r /path/to/animated-readme .claude/skills/animated-readme
cp .claude/skills/animated-readme/commands/animated-readme.md .claude/commands/

Then, in Claude Code:

Make an animated README for this repo.

Or run /animated-readme. Changed the copy later? /animated-readme render re-renders the GIFs from readme-scenes.json.

What you get

Documentation

• SKILL.md: the steps and rules Claude follows.
• Writing guide: the README order, the voice, the words to cut, and how to write alt text.
• python scripts/render.py --help and python scripts/record_html.py --help: every option.

Licence

Apache-2.0. See LICENSE and NOTICE. Made by Brian Arfi.