Index of every page on this site: llms.txt
All skills
robotostudio avatar

/generate-thumbnails-agentic

@c0b29e4
Run it yourself

Use when regenerating Sanity Studio page builder insert-menu thumbnails — screenshots every block from a temporary preview page and writes each block's thumbnail.png. Use when the user says "generate thumbnails", "regenerate the block thumbnails", or after a rebrand/theme change makes the existing tiles wrong. For a single new block, the new-block skill's step 7 points here.

  • 1 file
  • 21.9 KB
  • Updated 3 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/robotostudio/turbo-start-sanity/generate-thumbnails-agentic

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈102 tokens for metadata: the name and description. ≈5.5k when used: this file.

Description uses 5.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈407 characters, or 5.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Generate Page Builder Thumbnails

Overview

The Studio insert menu shows a grid of block previews. This skill regenerates that whole set: render every block on a throwaway page, screenshot each one, and write the result to each block's thumbnail.png.

Read CLAUDE.md → "Page Builder Pattern" first — the paths below are load-bearing.

How thumbnails actually work here

The source of truth is one thumbnail.png per block, co-located with it:

packages/sanity-blocks/src/<kebab-block>/thumbnail.png   ← write this
                    ↓  pnpm --filter studio sync-thumbnails  (also runs on postinstall)
apps/studio/static/thumbnails/preview-<kebab-block>.png  ← generated, do not edit

packages/sanity-blocks/scripts/sync-thumbnails.ts deletes every preview-*.png in the target directory and re-copies from the block folders. Anything you hand-write into apps/studio/static/thumbnails/ is gone at the next install.

<HARD-GATE> Write PNGs to `packages/sanity-blocks/src/<block>/thumbnail.png`. Never write into `apps/studio/static/thumbnails/` — that directory is generated. </HARD-GATE>

Format is fixed by previewImageUrl in apps/studio/schemaTypes/definitions/pagebuilder.ts, which camelCase→kebab-cases the schema name and appends .png:

  • PNG, not WebP — a .webp file 404s and the tile renders empty
  • 1200×800, matching every existing thumbnail
  • filename is the block's directory name (kebab-case: feature-cards-icon), not the schema type name (featureCardsIcon)

Prerequisites

  1. Playwright MCP is configured. Run a Playwright MCP tool (e.g. browser_navigate) to verify. It is not committed to this repo, so a fresh clone will not have it. If unavailable, STOP and ask the user:

    "This skill drives the browser through the Playwright MCP server. Please run this and restart Claude Code:"

    claude mcp add playwright -- npx @playwright/mcp@latest

    Do NOT proceed until the user confirms it is available.

  2. Image tooling. ffmpeg or sharp for the resize. Check first: command -v ffmpeg.

  3. The dev server is running on :3000. Check with curl -sI localhost:3000. If it isn't, ask before starting pnpm dev:web — don't auto-launch.

  4. Sanity credentials, to look at dataset images: NEXT_PUBLIC_SANITY_PROJECT_ID / NEXT_PUBLIC_SANITY_DATASET and SANITY_API_READ_TOKEN, from apps/web/.env.local (or .env). Step 3b additionally needs SANITY_API_WRITE_TOKEN — check it is non-empty before uploading, or the POST goes out with an empty bearer and fails confusingly.

Step 1: Discover the blocks

The block list is blockSchemas in packages/sanity-blocks/src/sanity-blocks.ts — ten at the time of writing. Each entry maps to a directory packages/sanity-blocks/src/<kebab>/ containing <kebab>.schema.ts, <kebab>.groq.ts, index.tsx, and thumbnail.png.

For each block, record:

  • the directory name (this is the output filename)
  • the exported component name — not derivable from the folder (cta → CTABlock, feature-cards-icon → FeatureCardsWithIcon, hero → HeroBlock). Copy the import block at the top of apps/web/src/components/pagebuilder.tsx; it already imports all ten with the right specifiers.
  • which fields carry images or video — read this from <kebab>.groq.ts, not the schema. The projection is what the component actually receives (see Step 2).

Step 2: Read the components and their GROQ

The render layer is packages/sanity-blocks/src/<kebab>/index.tsx, imported by apps/web/src/components/pagebuilder.tsx. Read the props of each.

<HARD-GATE> **Blocks here take GROQ-projected data, not raw Sanity field values.** The mock data must match the projection in `<kebab>.groq.ts`, not the schema.

Images are the trap. Components take SanityImageData from internal/sanity-image, which is what imageFields in internal/groq-fragments.ts projects:

image: {
  // a REAL asset id from Step 3 — this placeholder fails the regex below
  // and renders blank, which is the very failure this gate is about
  id: "image-<hash>-1200x800-jpg",   // asset._ref, flattened to a string
  alt: "Placeholder image",
  preview: null,                      // lqip, optional
  hotspot: null,
  crop: null,
}

A raw { _type: "image", asset: { _type: "reference", _ref } } renders nothing — resolveAssetId rejects it. What passes is an id matching /^image-[a-zA-Z0-9]+-\d+x\d+-\w+$/, in packages/sanity-blocks/src/internal/sanity-image.tsx. A leading drafts. is stripped, so draft asset ids are safe.

Same for video: read the muxVideoFields fragment, don't invent the shape — and note the hero does not take a plain video (Step 4). </HARD-GATE>

Step 3: Get image asset ids

Blocks with image fields need a real asset id or they screenshot blank.

3a. Use what's already in the dataset. Query it:

ENV_FILE=$(ls apps/web/.env.local apps/web/.env 2>/dev/null | head -1)
[ -n "$ENV_FILE" ] || { echo "no apps/web/.env.local or .env"; exit 1; }
set -a; source "$ENV_FILE"; set +a
PROJECT_ID=$NEXT_PUBLIC_SANITY_PROJECT_ID
DATASET=$NEXT_PUBLIC_SANITY_DATASET

curl -s -G "https://$PROJECT_ID.api.sanity.io/v2024-01-01/data/query/$DATASET" \
  -H "Authorization: Bearer $SANITY_API_READ_TOKEN" \
  --data-urlencode 'query=*[_type == "sanity.imageAsset" && !(_id in path("drafts.**"))][0...20]{ _id, originalFilename, metadata { dimensions } }'

Ask for 10–20, not 5 — you want options. The drafts.** exclusion matters: _id sorts drafts.* ahead of image-*, so without it the first ten rows are draft assets.

Every shell here is a fresh one — re-run the source line in each command block, or $PROJECT_ID is empty and the URL silently malforms.

<HARD-GATE> **Look at the candidates before picking.** The first landscape asset in a dataset is often a partner or competitor logo, or a branded marketing graphic. Pick it blind and that logo ends up across every hero tile in Studio. (This has happened.)

This one is a template, not copy-pasteable — substitute {hash}, {w}, {h} and {ext} from the asset's _id. Note the -f: without it a wrong substitution exits 0 and writes an 87-byte JSON error you will mistake for an image.

curl -fsS -o "/tmp/preview-<hash>.<ext>" \
  "https://cdn.sanity.io/images/$PROJECT_ID/$DATASET/<hash>-<w>x<h>.<ext>?w=400"

Read each file to actually see it. Reject anything carrying a third-party mark — except for the logo blocks: logo-cloud and cta.usedByTeams exist to show third-party logos, so real brand marks are the correct content there. </HARD-GATE>

Pick 5–8 varied subjects and spread them across blocks deliberately — one image repeated down the whole grid is a red flag.

3b. Only if the dataset has none, upload placeholders — and ask first, it writes to their dataset:

[ -n "$SANITY_API_WRITE_TOKEN" ] || { echo "SANITY_API_WRITE_TOKEN unset"; exit 1; }
curl -L -o /tmp/placeholder-landscape.jpg "https://picsum.photos/seed/thumb-land/1600/1200"

curl -s -X POST "https://$PROJECT_ID.api.sanity.io/v2024-01-01/assets/images/$DATASET" \
  -H "Authorization: Bearer $SANITY_API_WRITE_TOKEN" \
  -H "Content-Type: image/jpeg" \
  --data-binary @/tmp/placeholder-landscape.jpg

The response's _id (image-<hash>-1600x1200-jpg) is what goes in id. Offer to delete them in Step 7.

Step 4: Build the preview page

Create apps/web/src/app/thumbnails/page.tsx, importing block components directly from @workspace/sanity-blocks/<kebab>/index — not through PageBuilder, which needs Visual Editing context.

<HARD-GATE> Mark it `"use client"`. Several blocks pass function props to client libraries (`DynamicIcon` fallbacks, Radix primitives, `useFormStatus`) which cannot cross the RSC boundary — a server component throws "Functions cannot be passed directly to Client Components". </HARD-GATE>

Wrap each block so the screenshot step can find it. Use the directory name, since that's the output filename:

<div data-block="feature-cards-icon">
  <FeatureCardsWithIcon {...mock} />
</div>

Mock data rules:

  • Contextual copy, not lorem ipsum — a hero gets a real headline, a FAQ gets plausible questions. These are what editors browse.

  • Rich text is Portable Text, never a plain string: [{ _type: "block", _key: "k1", style: "normal", markDefs: [], children: [{ _type: "span", _key: "s1", text: "…", marks: [] }] }]

  • Images use the flattened shape from Step 2's gate.

  • No array item needs _type — these are plain typed interfaces (FeatureCard, LogoCloudLogo, ShowcaseGridItem), not discriminated unions. Give every item a unique _key anyway (required on ShowcaseGridItem and LogoCloudLogo, optional on the rest), and note FaqItem needs a required _id as well as its optional _key.

  • video-feature takes video: { asset: { playbackId, policy: "public", status: "ready", … } }, or renders its copy with no video.

  • The hero is different, and getting it wrong blanks the most prominent tile. video is not a video — it is a light/dark variant object, each variant carrying mediaType plus a poster or a Mux/webm source (hero/hero-video.tsx, HeroVideoData). With no poster and no Mux still it renders nothing, so a full-viewport blank. Give both variants a poster:

    video={{
      light: { mediaType: "sanity", poster: img(POSTER_ID, "…") },
      dark:  { mediaType: "sanity", poster: img(POSTER_ID, "…") },
    }}
  • Don't reach for as any or @ts-expect-error. The page type-checks clean if you read the interfaces, and silencing the checker hides exactly the shape mistakes Step 2 warns about — wrong image shape, FaqItem missing _id — which fail by rendering blank, not by erroring.

  • Don't put a background colour on the wrappers — it adds noise to every tile.

Step 5: Screenshot each block

Use the Playwright MCP tools in sequence:

  1. Set the viewport — browser_resize to 1440×900.
  2. Navigate — browser_navigate to http://localhost:3000/thumbnails.
  3. Wait for render — let the network settle before touching anything.
<HARD-GATE> **Pin the colour scheme; never inherit the browser's default.** A fresh Playwright Chromium has no dark preference, so this site renders **light**, while a normal dev session renders dark. Captures and Step 6's padding must agree, and the tiles should match what editors see in Studio.

There is no browser_emulate_media tool, and media emulation alone is not enough here: the site runs next-themes with attribute="class" and defaultTheme="system" (apps/web/src/components/providers.tsx), so the theme is a class on <html> backed by localStorage. Media emulation only wins when no theme is stored.

The reliable route is to set it directly, then reload:

browser_evaluate: () => {
  localStorage.setItem("theme", "light");   // or "dark"
  location.reload();
}

Then pad to match in Step 6. </HARD-GATE>

<HARD-GATE> **Hide the layout chrome before capturing.** The real site wraps this page: a `header` from `apps/web/src/components/navbar.tsx` (`z-40`, `lg:sticky` — sticky at the 1440px viewport used here) and a `footer` from `components/footer.tsx`.

The hero also draws its own lg:fixed strip, #hero-fold (hero/index.tsx), which stitches into tall captures exactly like the header does and is not matched by the chrome selector.

Easy to miss, because it only affects some blocks: one shorter than the viewport captures clean, since the header sits outside the element bounds. One taller is stitched by scrolling, so the header rides along and bakes in across the middle of the image — cta at 765px was clean, showcase-grid at 1402px had the navbar through the centre.

Inject once after navigating, and again after any reload:

browser_evaluate: () => {
  const s = document.createElement("style");
  s.textContent =
    "header,footer,nextjs-portal,#hero-fold{display:none !important}";
  document.head.appendChild(s);
}

nextjs-portal is the Next dev indicator. </HARD-GATE>

Then, for each block:

  • scroll [data-block="<kebab>"] into view (this is also what loads its images — they are loading="lazy")

  • wait for that block's images to actually decode, rather than guessing a delay:

    browser_evaluate:
      target:   [data-block="<kebab>"]
      element:  "the <kebab> block"
      function: (element) => {
                  const imgs = [...element.querySelectorAll("img")];
                  return {
                    total: imgs.length,
                    loaded: imgs.filter((i) => i.complete && i.naturalWidth > 0).length,
                  };
                }

    The one-argument form receives the resolved element named by target — you cannot pass it a selector string, so query relative to element rather than reaching for document.

    It returns counts, not a boolean, because .every() is true for a block with no images at all — which is exactly the blank capture you are trying to catch. Compare total against the images your mock gave that block: equal and fully loaded means go; total: 0 on a block you gave images to means the id was rejected (Step 2's gate), not that it is ready.

    Poll until loaded === total, and stop with an error after a few seconds — a block that never loads should fail loudly, not screenshot blank. This is not theoretical: on a real run showcase-grid reported {total: 6, loaded: 2} immediately after the page settled.

  • browser_take_screenshot scoped to that element — pass the selector as target (it accepts a snapshot ref or a unique selector) plus a human element description, and filename .playwright-mcp/<kebab>-raw.png. Do not set fullPage; it cannot combine with an element screenshot.

<HARD-GATE> **Always prefix `filename` with `.playwright-mcp/`.** The server sandboxes writes to two roots — its working directory (the repo root) and `.playwright-mcp/` under it:
  • a bare <kebab>-raw.png writes to the repo root, dropping ten untracked PNGs next to package.json. Verified: it reports success and litters the repo.
  • an absolute path outside those roots is rejected: File access denied: … is outside allowed roots. /tmp/thumbnails/… does not work.
  • .playwright-mcp/<kebab>-raw.png is accepted and is already gitignored-by- cleanup in Step 7.</HARD-GATE>

Then move them where Step 6 expects:

mkdir -p /tmp/thumbnails && mv .playwright-mcp/*-raw.png /tmp/thumbnails/

Sanity-check the captures before processing. A mean-luminance read spots an empty one faster than opening ten files:

for f in /tmp/thumbnails/*-raw.png; do
  printf "%-24s %s\n" "$(basename "$f" -raw.png)" \
    "$(ffmpeg -hide_banner -i "$f" -vf signalstats,metadata=print:key=lavfi.signalstats.YAVG \
       -f null - 2>&1 | grep -o 'YAVG=[0-9.]*' | head -1)"
done

A capture sitting at the bare background value — ~19 dark, ~230 light — is empty. Look at any that do before processing.

Step 6: Process and place

Target: 1200×800 PNG, full block width preserved.

<HARD-GATE> Do not `fit: 'cover'` or centre-crop. Blocks render 1440px wide; a cover-crop zooms in and clips the sides, cutting off titles and dropping cards. Scale width to 1200 first, then crop height from the top, padding if short. </HARD-GATE>

Pad with the background of the theme you captured in — white for light, black for dark. Padding and capture must agree or every short block gets a band across it. Read it rather than assuming: browser_evaluate: () => getComputedStyle(document.body).backgroundColor.

export PAD=white   # must match Step 5's colour scheme; exported so sharp sees it too
for f in /tmp/thumbnails/*-raw.png; do
  name=$(basename "$f" -raw.png)
  out="packages/sanity-blocks/src/${name}/thumbnail.png"
  ffmpeg -y -loglevel error -i "$f" \
    -vf "scale=1200:-1:flags=lanczos,crop=1200:min(ih\,800):0:0,pad=1200:800:0:(oh-ih)/2:$PAD" \
    "$out" || { echo "convert failed: $name"; exit 1; }
  [ -s "$out" ] || { echo "no output: $out"; exit 1; }
done

Stop on the first failure rather than pressing on — sync-thumbnails copies whatever is on disk, so a half-finished run silently republishes stale tiles.

Two shapes need checking afterwards:

  • Blocks much taller than 3:2 (showcase-grid, video-feature, hero run 1000–1400px) lose their lower half to the crop — the hero's headline can end mid-word. Usually fine; the tile only has to be recognisable.
  • Thin strips (logo-cloud is ~72px) become a band floating in centred padding — the command already centres it. Accept it, or capture that block with some surrounding space.

sharp equivalent, if ffmpeg isn't around. require('sharp') fails from the repo root — it exists only transitively under node_modules/.pnpm/, so this needs an install first, and unlike the ffmpeg version it is not wired into a loop:

export PAD=white
for f in /tmp/thumbnails/*-raw.png; do
  name=$(basename "$f" -raw.png)
  IN="$f" OUT="packages/sanity-blocks/src/${name}/thumbnail.png" node -e "
const sharp = require('sharp');
const PAD = process.env.PAD || 'white';
(async () => {
  const buf = await sharp(process.env.IN).resize(1200, null).toBuffer();
  const { height } = await sharp(buf).metadata();
  const top = Math.floor((800 - height) / 2);
  const pipeline = height >= 800
    ? sharp(buf).extract({ left: 0, top: 0, width: 1200, height: 800 })
    : sharp(buf).extend({ top, bottom: 800 - height - top, background: PAD });
  await pipeline.png().toFile(process.env.OUT);
})();
" || { echo "convert failed: $name"; exit 1; }
done

Then sync and check the Studio menu:

pnpm --filter studio sync-thumbnails

There is no schema step. insertMenu.views is already wired in definitions/pagebuilder.ts and derives from blockSchemas, so a block with a thumbnail.png appears automatically. There are no insertMenu.groups in this repo — don't add them unasked.

Step 7: Clean up

rm -rf apps/web/src/app/thumbnails/   # the preview page — dead code, regenerate when needed
rm -rf /tmp/thumbnails/               # raw screenshots
rm -rf .playwright-mcp/               # only if a browser tool created it

If you uploaded placeholders in 3b, ask whether to delete them from the dataset. If you used existing assets, nothing to undo.

Leave behind only the modified packages/sanity-blocks/src/*/thumbnail.png files and their synced copies under apps/studio/static/thumbnails/.

Common Mistakes

Mistake Fix
Writing to apps/studio/static/thumbnails/ Generated dir — sync-thumbnails wipes it. Write packages/sanity-blocks/src/<block>/thumbnail.png
WebP output previewImageUrl builds a .png path — WebP 404s and the tile is blank
camelCase filename Use the kebab-case directory name (feature-cards-icon), not the schema type (featureCardsIcon)
Raw image refs in mock data Blocks take projected { id, alt, preview, hotspot, crop } — { asset: { _ref } } renders nothing
Cropping with fit: cover Scale width to 1200 first, then crop/pad height
Preview page as a server component Must be "use client" — function props can't cross the RSC boundary
Adding insertMenu config Already wired and generated from blockSchemas — nothing to add
Letting the browser pick the colour scheme A fresh Playwright Chromium renders light, a dev session renders dark — pin it, and pad to match
Layout chrome baked into tall tiles The sticky header (z-40) stitches into the middle of any block taller than the viewport — hide header,footer,nextjs-portal first
Screenshotting before scrolling Images are loading="lazy" — a block only loads its images once scrolled into view
Hardcoding the pad colour Pad with the captured theme's background, or the tile gets a glaring band
Missing _key on mock array items No item needs _type. _key is required on ShowcaseGridItem/LogoCloudLogo, optional elsewhere; FaqItem also needs a required _id
Rich text as a plain string Portable Text block format only
Going through PageBuilder Import block components directly — PageBuilder needs Visual Editing context
Grabbing the first landscape asset View candidates first — it's often a partner logo
Uploading to the dataset unasked Check for existing assets, then ask
Leaving app/thumbnails/ behind Delete it — dead code, and this skill regenerates it
Generic placeholder copy Write contextual text; editors browse these tiles

Red Flags — stop if you notice these

  • You're about to write a .webp, or write anything into apps/studio/static/thumbnails/ — stop, wrong format and wrong directory
  • Your mock image is { asset: { _ref: … } } — stop, that renders blank here
  • You're adding insertMenu config to pagebuilder.ts — stop, it's generated
  • You're about to fit: 'cover' — stop, it clips wide blocks
  • The preview page has no "use client" — stop, it will crash
  • Image areas are blank on a capture — stop, fix before processing (check you scrolled the block into view first; the images are lazy)
  • You haven't pinned the colour scheme — stop, the tiles won't match Studio
  • You haven't hidden header/footer/nextjs-portal — stop, the navbar bakes into tall tiles
  • You're uploading to someone's dataset without asking — stop

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at c0b29e4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 months ago

README badge

README badge for robotostudio/turbo-start-sanity/generate-thumbnails-agentic