agentleFS
yschimkeyschimke/compose-ai-tools/.claude/skills/render-evidence/SKILL.md

render-evidence

Skill127 starsChanged 37 days agoApache-2.0View on GitHub

Capture the before/after rendered PNGs a UI-affecting PR in this repository needs as visual evidence, including bringing an Android SDK up in a fresh sandbox. Use when a change touches a Compose @Preview, a catalog, the VS Code webview, an overlay, a theme, an icon or a fixture, and the PR body needs real pixels.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read the sticky <!-- preview-diff --> comment on the PR — CI may already have rendered and diffed exactly the surface you changed.

    line 17
  2. Distinctive:

    Read that before improvising.

    line 69
  3. Distinctive:

    Commit the PNGs you intend to cite to your working branch and push.

    line 89
  4. Very specific:

    Write !alt plainly and leave any backticks that appear alone.

    line 96
  5. Very specific:

    Verify the pixels actually render on the published page before claiming evidence.

    line 101

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Capturing visual evidence

Root AGENTS.md says a UI-affecting PR must carry before/after evidence as embedded, viewable images — describing an image, or deferring to the diff bot's auto-comment, does not count. This is how to produce them here.

Check what already exists first

Rendering is not free. Before capturing anything:

  • Read the sticky <!-- preview-diff --> comment on the PR — CI may already have rendered and diffed exactly the surface you changed.
  • Reuse renders published on the compose-preview/pr and compose-preview/main branches where they cover the change.
  • Scan .github/workflows for the preview-diff CI this repo already runs, and cite it.

The bot's comment is a convenience, not a substitute: your PR body still needs your change's before/after embedded in it.

Rendering

Whole sample modules:

./gradlew :samples:android:composePreviewRenderAll
./gradlew :samples:cmp:composePreviewRenderAll

One preview, which is what a before/after pair usually wants:

./gradlew :samples:android:composePreviewRender --rerun \
  -PcomposePreview.filter=<PreviewFunctionName>

--rerun matters. A failed render leaves .error.json sidecars that count as task outputs, so composePreviewRender goes UP-TO-DATE and re-reports the stale failure. PNGs land under <module>/build/compose-previews/renders/.

The samples consume the plugin through includeBuild("gradle-plugin"), so a plugin edit is picked up with no publish step.

For the before side, render at the base commit (git stash, or a worktree at origin/main) into a separate directory before rendering the head.

The Android lane needs an SDK; the Desktop lane does not

  • Compose Desktop renders headlessly — no DISPLAY, X server or xvfb. Skia's software path draws offscreen. If a desktop render looks broken in a sandbox, it is almost never the windowing system: check the JDK 17 toolchain and the native deps first, per Common commands and docs/DESKTOP_NATIVE_DEPS.md.
  • The Android/Robolectric lane needs an Android SDK, which a fresh container does not have. scripts/install.sh --android-sdk installs it (and a JDK when ./gradlew reports "Unable to download toolchain"). The traps that cost a whole session — chiefly that the platform package for compileSdk = 37 is platforms;android-37.0, not android-37, and that the wrong name fails the entire sdkmanager invocation it appears in, taking the SDK 36 packages down with it — are written up under Bringing up a fresh sandbox. Read that before improvising. Cold end-to-end run is about 3 minutes.

Surfaces the @Preview pipeline does not reach

  • VS Code panel UI (src/webview/, media/preview*.css) has its own capture path: the preview-harness boots the real <preview-app> bundle headlessly against fixture JSON. Loop and fixture authoring are in preview-harness/README.md; seed fixtures are grid-default and a11y-findings.
  • A semantics overlay has a renderable proxy: the compose/semantics-wireframe SVG.
  • Anything genuinely uncapturable here (a three.js webview in a headless container): say so explicitly in the PR body, embed a proxy if one exists, and state how a human or CI verifies it visually. Then treat "nothing renders this yet" as a gap to close in the same or a fast-follow PR — register a fixture or a @Preview with the preview-harness so the next change to that surface is diffed automatically.

Getting the pixels into the PR

  1. Commit the PNGs you intend to cite to your working branch and push.
  2. Embed them as markdown images whose URLs are commit-SHA-pinned raw.githubusercontent.com links to those pushed files — the same form the diff bot uses. This is not just convention: a ![alt](url) whose host is not a GitHub origin has its ! stripped before it reaches the API, silently, so a deployment URL or a CDN link arrives as a bare link and the evidence is gone. Committing and citing the raw URL is what makes the image survive.
  3. Write ![alt](url) plainly and leave any backticks that appear alone. They are injected between the agent and GitHub, and the PR Body Syntax workflow repairs them in place. The three cases it does not cover — review comments, destinations mangled past recognition, and a picture that still did not render — are in PR workflow.
  4. Verify the pixels actually render on the published page before claiming evidence. WebFetch caches per URL for ~15 minutes; bust it with a throwaway query parameter rather than chasing a bug you already fixed.

A before/after pair whose two images look identical is a finding, not a failure — either the change is not visual, or the render did not pick it up. Say which.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.