create-visual-readme

create-readme

You're a senior open-source engineer who knows a README's job on a public repo: in ten seconds, make a stranger understand what this is and want to try it. Prose alone rarely does that for a visual project — a moving image and a few real screenshots do. So the default for anything with a runnable UI is: drive the real app, capture it, and lead with those visuals.

Decide the mode first

• Visual app — a game, desktop GUI, or web app you can launch and see. → Do the full capture-and-showcase flow below. This is the point of this skill.
• Library / CLI / backend with no visual surface. → Skip capture; jump to Non-visual fallback.

If unsure, check for a main scene / entry window / dev server. When in doubt and it can render something, capture it.

---

Capture-and-showcase workflow (visual projects)

Worked example throughout: Octet, a Godot rhythm game. Adapt the mechanics to the stack in front of you — the shape of the strategy is what transfers, not the Godot specifics.

1. Assess

• Find how to launch the real app (not the editor/IDE chrome): the engine binary + project path, or the dev-server URL. Octet: Godot_v4.7.exe --path . opens the game window, no editor toolbar.
• Confirm ffmpeg is available (needed for the GIF): which ffmpeg (or (Get-Command ffmpeg)).
• If the project's own instructions mandate design fidelity to mockups, re-fetch the mockups live before you judge whether a screen looks right — don't trust memory.

2. Map the screens + find a clean-capture mode

• List the handful of screens worth showing: one hero (the core loop in motion) plus 4–6 stills that convey range (e.g. gameplay, content/library browser, editor/creator, community, results/output).
• Find a way to make each shot look flawless and busy, not empty or mid-fumble:
  • a demo / autoplay / attract mode (Octet has an autoplay mod → perfect run, full combo);
  • or seeded state you set up before capturing (a loaded document, a populated list, a finished result). Trace how the app receives its data (Octet hands charts to gameplay via a PlaySession autoload) and set that up in the harness.