readme-showcase

name

readme-showcase

description

Capture polished screenshots and an optimized demo GIF/MP4 of a deployed web project and embed them into that project's GitHub README behind an idempotent SHOWCASE marker block. Use whenever the user asks to "add screenshots to a README", "record a demo of <project>", "showcase <project>", "update project images", "make a demo GIF", wants visitors to see what a project looks like without opening the live link, or wants any deployed project to look better on GitHub — even if they don't say "showcase". Works on any live URL; no install needed in the target repo. Generates assets locally and ALWAYS stops for user review before any commit; never pushes on its own.

README Showcase

Turn a deployed web project into README-ready visuals: hero/mobile/full-page screenshots (WebP) plus a short interaction recording shipped as a GIF (the only video format GitHub READMEs auto-play) and an MP4 (higher quality, for manual drag-upload into GitHub comments/releases). Everything is driven by a small showcase.scenario.json committed into the target repo, so captures are reproducible and diffable — re-run the skill after a redesign and the README refreshes itself.

All scripts live in this skill's scripts/ directory and need no npm install anywhere: they resolve playwright-core from the machine (local dep → PLAYWRIGHT_CORE_PATH → global npm root) and use ffmpeg (+ optionally sharp-cli) from PATH. <skill> below means this skill's directory.

Owner config (edit for your machine)

• Project inventory (optional): D:\github_repository\ChanMeng666\data\profile.yaml — projects array with id, name, url, repoUrl, demoUrl, tier, status.
• Local clones root: D:\github_repository\<repo-name>

If no inventory exists, just ask the user for the live URL + local repo path.

Workflow

1. Pick the project

If the user named a project, match it in the inventory (or take a URL/path they gave directly). Otherwise list candidates that have a live url:, ordered by tier/priority, and ask which to capture. Locate the local clone; if the repo isn't cloned, offer gh repo clone before proceeding.

Use a scratch dir for intermediates (never inside the target repo): <work> = a temp/scratch folder for this run.

2. Probe the live site

node <skill>/scripts/probe.mjs --url <liveUrl> --work <work>/probe

Read survey.json and look at the three probe screenshots yourself (Read tool). Decide:

• which 2–4 pages tell the story (hero is mandatory; add the 1–2 most product-defining inner pages + one mobile shot)
• a 15–25 second demo storyline: the single most impressive interaction a first-time visitor should see (type something → result appears; pick an option → output changes). Hunt for selectors with a quick page.evaluate if the probe shots aren't enough.
• whether a cookie/consent banner needs an optional setup click
• login wall: if survey.json says loginWall: true, set it in the scenario, capture only the public surface (landing + login screen), skip the demo unless the public surface has one, and say so in the final report. Never attempt credentials.

3. Write the scenario

Write <targetRepo>/docs/showcase/showcase.scenario.json. If one already exists from a previous run, update it instead of regenerating — it may contain hand-tuned steps. Full schema + site-type recipes (multi-page app, single-purpose tool, API service): references/scenario-schema.md. A real example: examples/gradient-svg-generator.scenario.json.

If the repo already has an established screenshots/assets directory referenced by its README, use that as outDir instead of docs/showcase.

4. Capture and encode

node <skill>/scripts/capture.mjs <scenario> --work <work>/cap
node <skill>/scripts/media.mjs --work <work>/cap --out <targetRepo>/<outDir>

On a failed step, stderr names the failing scenario index — fix the scenario and re-run just that part (--only demo, --only screenshots, or --page <label>).

Quality gate — non-negotiable: Read every produced .webp and a frame of demo.gif yourself before showing the user. Blank areas, cookie banners in frame, fallback fonts, half-loaded images, or a demo that doesn't visibly do anything → fix the scenario and re-capture. media.mjs exits non-zero if the GIF can't fit 7.5 MB; the fix is a shorter demo, not lower quality.

5. Update the README

Insert or replace the marker block in <targetRepo>/README.md:

<!-- SHOWCASE:START — generated by readme-showcase; edit docs/showcase/showcase.scenario.json and re-run instead of hand-editing -->
...
<!-- SHOWCASE:END -->

If the markers exist, replace only what's between them (idempotent). If not, insert after the title/badge block and before the table of contents or first ## section. Use relative paths so both GitHub and local previews render. Block templates per site type: references/readme-block.md.

6. Review gate — hard stop

Show the user: the file list with sizes, the README diff, and the images (render them, don't just name them). Do not commit anything until they approve. On approval, commit in the target repo:

docs: add showcase screenshots and demo recording

Generated by readme-showcase (scenario: docs/showcase/showcase.scenario.json)

Push only when the user explicitly says push. After pushing, optionally offer to point the project's image: field in the inventory at the raw GitHub URL of hero.webp (separate commit in the inventory repo).

When things go wrong

references/troubleshooting.md covers: cookie banners, carousels/animations, font flashes, lazy-load images, fullPage limitations (inner-scroll layouts can't be fullPage-captured — use viewport shots + scroll actions), networkidle hangs, GIF banding on gradient-heavy sites, and chromium version drift.