docs-webp

name	docs-webp
description	Convert displayed PNG/JPG/JPEG screenshots referenced by Expo docs MDX pages to lossy WebP, update their references, verify the converted files, and trash original PNGs/JPGs/JPEGs only when no docs page still references them. Use when asked to convert or optimize PNG screenshots in a file or directory under `expo/docs/pages/`. Do not use for JPEG, SVG, or images outside Expo docs.
argument-hint	<mdx-file-directory-or-section>
version	1.0.0

Convert Expo docs PNG/JPG/JPEG screenshots

You are an image-conversion assistant for Expo docs pages:

• Your goal is to convert PNG/JPG/JPEG screenshots to lossy WebP, rewrite references, and trash the original files.
• Accept only files and directories under expo/docs/pages/.
• Never edit pages/versions/latest/.
• q80 cuts a typical screenshot by ~70% with no visible difference and passes Lighthouse's "next-gen formats" audit.
• Keep the PNG/JPG/JPEG and report the failure when quality is unacceptable.

Preflight

Preflight

Require bun, cwebp, and trash:

command -v bun
command -v cwebp
command -v trash

If a required command is missing, report it and stop. Install cwebp with brew install webp and trash with brew install trash on macOS.

Step 1: Convert

Resolve scripts/convert.ts relative to this SKILL.md, then run:

bun <skill-directory>/scripts/convert.ts <scope>

Use quality 80 unless the user explicitly requests another value:

bun <skill-directory>/scripts/convert.ts <scope> --quality=<number>

Handle each result as follows:

Line	Meaning	Your action
CONVERTED <ref> <pngKB> <webpKB> <saved%>	.webp written next to the PNG	Rewrite this ref
EXISTS <ref>	Already converted on a prior run	Rewrite if the .mdx still points at .png; otherwise nothing
SKIPPED <ref>	WebP wasn't smaller	Leave it as PNG; do nothing
MISSING <ref>	PNG not on disk	Report it; don't invent a file

Step 2: Rewrite references and verify

For each CONVERTED or applicable EXISTS result:

• Each /static/images/... ref is unique.
• Replace only the reported src or darkSrc reference in the scoped MDX files.
• Confirm that the new .webp reference resolves under /public/.
• Confirm that the converted PNG/JPG/JPEG reference no longer appears in the scoped MDX.
• Inspect text-heavy or fine-detail screenshots when image viewing is available.
• If a newly converted WebP has unacceptable artifacts, restore its PNG reference, trash only the newly created WebP, and report it.
• Don't touch SKIPPED images, and don't touch require('@/assets/...png') paths in code fences (those are sample code). The script never reports them.

Step 3: Report and let the user look

Summarize the savings, for example:

> Converted 12/14 PNGs in pages/eas: 4.1 MB to 1.2 MB (71% saved). 2 skipped (WebP not smaller).

The original PNGs are still on disk, so reverting is just undoing the reference edits. q80 is visually near-identical, but text-heavy screenshots (diagrams, status bars, fine UI labels) are where a lossy artifact could show. Offer the user a local look before you delete anything.

Step 4: Cleanup

Work one section at a time. For each converted image, confirm nothing else still needs the PNG, then trash it:

grep -rl "static/images/<path>/<name>.png" <docs-root>/pages   # nothing? safe to remove
trash <docs-root>/public/static/images/<path>/<name>.png

If a page outside the scope still references the .png, keep it and say so. The image carries both formats until that page is converted too, which is fine. PNGs also remain in git history until commit, so this step is recoverable.

Step 5: Run the asset-reference test

After rewriting references and cleaning up originals, run the targeted Expo docs test from <expo-root>/docs:

node --experimental-strip-types --experimental-vm-modules ./node_modules/jest/bin/jest.js checks/check-asset-refs.test.ts --runInBand

Require both tests in the docs asset references suite to pass. If the test fails, restore the missing asset or correct its reference, then rerun the test. Do not report completion until it passes.