# Readme Showcase

> Add or swap feature-showcase blocks (GIF + full-video links) in the repo-root README. Use when the user wants a new feature demo on the README, wants to replace the text-animation/sticker showcase video, or asks to "把视频/动图放到 README 上".

- Skill: `quriosity-agent/readme-showcase` (Agent Skill)
- Install (CLI): `npx skillmds@latest add quriosity-agent/readme-showcase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/quriosity-agent/readme-showcase/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: quriosity-agent (https://skillmd.com/u/quriosity-agent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/quriosity-agent/readme-showcase

---


# README Showcase

The repo-root `README.md` (NOT `qcut/README.md` — it lives one level above the
`qcut/` package dir) carries feature showcases inside marker-delimited blocks:

```
<!-- showcase:<slug>:start -->
...swappable content...
<!-- showcase:<slug>:end -->
```

Existing slugs: `text-animations`, `stickers` (reserved). **Only ever edit
between a block's markers** — everything outside (Product Tour screenshots,
Why/Features, Quick Start) must survive swaps untouched.

## Adding or swapping a showcase

1. **Pick the source video** — a verified 2K60 final (e.g. from
   `~/Documents/QCut/e2e/<project>/`). Never use an unverified cut; run the
   frame-by-frame QA from `qcut-shot/references/promo-iteration-lessons.md`
   first if in doubt.

2. **Generate the hero GIF** (autoplays on GitHub; videos in `<img>`/`<video>`
   tags do not). Budget: **≤5 MB committed**. Recipe that hit 2.9 MB for a
   10 s, 960 px, 3-excerpt montage:

   ```bash
   ffmpeg -y -i FINAL.mp4 -filter_complex \
     "[0:v]trim=A1:A2,setpts=PTS-STARTPTS[a];\
      [0:v]trim=B1:B2,setpts=PTS-STARTPTS[b];\
      [0:v]trim=C1:C2,setpts=PTS-STARTPTS[c];\
      [a][b][c]concat=n=3:v=1:a=0,fps=14,scale=960:-1:flags=lanczos,split[x][y];\
      [x]palettegen=max_colors=128[p];[y][p]paletteuse=dither=bayer:bayer_scale=4" \
     qcut-<slug>.gif
   ```

   Pick excerpts that show: the feature happening (not UI navigation), one
   "wow" beat, and the branded outro. Verify content by extracting tiles
   (`select='eq(n\,..)',tile`) before committing — never ship a GIF unseen.

3. **Place assets**
   - GIF → commit at `qcut/docs/assets/readme/qcut-<slug>.gif`
     (README references it as `qcut/docs/assets/readme/...` because the README
     sits at the repo root).
   - Full MP4s (ZH + EN) → upload to a **published GitHub release** for a
     stable hotlink, e.g.
     `gh release upload v20XX.XX.XX.X EN.mp4 ZH.mp4 --clobber`.
     Release-asset URLs
     (`https://github.com/Quriosity-agent/qcut/releases/download/<tag>/<file>`)
     are permanent; the tag does not need to match the feature's version.

4. **Edit the block** between the slug's markers only: `<img>` for the GIF +
   one "▶ Full promo" line linking both language MP4s. For a brand-new
   feature, add a new `### <Feature>` heading + fresh marker pair at the TOP
   of Product Tour and demote the previous "✨ new" badge.

5. **Verify** — `git diff` must show changes only inside the markers (plus
   the new binary asset); check the GIF file size; view the rendered README
   on the PR's Files tab before merging.

## Gotchas

- GitHub only autoplays GIF/animated-WebP in READMEs. `<video>` tags and
  release-asset mp4 links render as plain links, which is why the GIF + link
  combo exists.
- The `readme/` screenshots convention (PNGs ~600 KB) predates this skill;
  don't replace those static shots when swapping showcase blocks.
- Keep one "✨ new" badge at most — it's a spotlight, not a label.