compose-preview
Render a Jetpack Compose or Compose Multiplatform @Preview to PNG and look at it. Use when asked to render, show or check what a composable, @Preview or Material/Wear library component looks like, to verify a Compose UI edit, to compare before/after, or to review previews against design guidelines. Also to run an Android APK without an emulator.
How do I install this agent skill?
npx skills add https://github.com/yschimke/skills --skill compose-previewIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill 'compose-preview' provides tools for rendering Jetpack Compose previews. It includes installation scripts that fetch components from the author's GitHub repository and other technology-specific services. The skill uses a rendering daemon to process Kotlin code into images. No malicious patterns were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Compose Preview
Render @Preview composables to PNG without Android Studio (Android via
Robolectric, CMP Desktop via Skia). CLI, Gradle plugin and renderers ship from
compose-ai-tools; the MCP server
from compose-preview-server.
Render first
For a request to render or show a preview, follow the short loop below. For a requested guidelines review, use the review checklist to choose the local, hosted or UI Builder lane before invoking tools. Published catalogs and server-homed designs use hosted tools first; a missing local checkout does not require cloning, Gradle or a cloud environment. If tools are unavailable, report blocked evidence and follow the integration's setup guidance.
With the local MCP server attached (compose-preview-server 3.78.0+), its
initialize instructions say how to call it: render_preview preview=<FunctionName>, no exploring or registering first, no hand-built
mocks. Follow them. This skill adds the budget: a routine render is at most
three tool calls, with no base64 in the reply and images only when you need to
see them.
Your first call is the render. Don't grep for the preview or read its source first: the server finds it by function name. Look things up only if the render fails.
- Render. If your client reads local files (Claude Code, Codex, Gemini
CLI, OpenCode, Antigravity), pass
inline=false. The result ispngPath,sha256, dimensions andchanged, with no image tokens. If it listsotherMatches, render one only if the person asked about it. If it carries avariantChoicewhosemessagesays to ask (several previews matched and the host showed no chooser), the person picks, not you: reply with the rendered match and every entry inchoicesas a numbered list, ask which one they meant, and stop. Don't pick one or shorten the list to "other variants are available". A grid result or a declined choice needs no question. - Look only when you need to. Read
pngPathwith your file reader before you describe or judge the UI; that is what the person sees. Skip the read whenchangedorsha256already answers the question, such as "did my edit land?". Describe only what you saw. If you can't view images here, say so plainly. Never claim a visual check you didn't make.changedonly means the pixels differ from an earlier render; it can betrueon the first render of a session and it says nothing about how they changed. To say an edit looks right ("the title is bigger", "verified", "fixed"), readpngPathfirst. If you didn't, or a render failed, say the result is unverified. - Reply briefly, with
pngPathso the person can open the same image. Don't write "the image above": in a terminal or print-mode harness the person doesn't see images your tools return. Point atpngPathinstead.
Library components come from the catalog. When the person names a
library component (Material 3, Wear M3 EdgeButton, …) rather than one of
their own previews, use the hosted catalog server (compose-preview-catalog):
catalog_list_previews, then read the published snapshot with
resources/read. Request live access only to change knobs with
catalog_render_preview. Never add preview files to the person's project
to show a library component unless they ask for one. See
catalog-mcp.md.
Sweeps use hashes. For more than one render (variants, devices, font
scales, locales, a before/after check), pass observe=hash or use
render_matrix with contactSheet: false, which returns per-cell hashes
only. Fetch pixels only for the final screen or the cells whose hash moved,
or that you must judge by eye: one render_preview per such cell (its
overrides or uri, inline=false) and one read of its pngPath.
Design guidelines review. When asked to review a preview or catalog design
against Android design guidance, read
design-guidelines.md. It covers keyless
agent review, published results and the CLI's compose-preview review loop,
including explicit surface selection, required pictures and incomplete
coverage. A project with no guidelines of its own reviews against the shared
rule packs chosen by what each preview draws (widgets need the widget packs
and a @LauncherWidgetPreview), not a component catalog. It is in the default
skill bundle; the optional PR-review bundle is not required.
Hand multi-render reviews to design-reviewer. If a design-reviewer
subagent is available (the compose-agent-plugins plugins ship one), delegate
accessibility, font-scale, round-device and other matrix checks to it so the
images stay out of your context, and relay its verdict and paths. Give it the
subject, home/revision, catalog rules and requested coverage. Without one, run
the same checklist yourself and report that delegation was unavailable.
For a routine hash sweep, keep contactSheet: false. A requested visual
guidelines comparison needs pixels: inspect its required frames even in your
own context when no reviewer exists. Prefer only the relevant individual
images or a bounded comparison sheet, and never claim visual coverage from
hashes alone.
After a source edit, call render_preview again. notify_file_changed is
optional. If the result says it is stale, make exactly one more call with
force: {"reason": "<why>"}. Never run ./gradlew, clean, or delete
build/ dirs to chase a render; if a forced render is still wrong, read
mcp.md § Troubleshooting
(start with compose-preview mcp doctor).
Details on request. Add details: ["a11y", "layout"] only when the
person asks about accessibility or layout. observe=png returns inline pixels
for clients that can't read files.
No MCP tool? Use the CLI: compose-preview show --json --filter <Name>,
then read the entry's pngPath. Stale: --force=<reason>, once. See
cli.md. On either path, only output from the render
tools is a render: never a hand-built HTML, CSS or SVG mock. Report a failed
render with its error.
Running the whole app, not one composable? To drive or test an APK the
way an emulator would (navigation, deep links, runtime permissions, foldable
postures, a second display, offline or slow networks, BLE peripherals, home-screen
widgets, a Wear app with its tiles, ambient mode and phone sync), or to see an
edit running with live reload (launch --project, reload), use
compose-preview launch <app.apk> or the MCP simulator_* tools: Robolectric's
simulator, no emulator or device. Read simulator.md
first; a @Preview render stays the cheaper check for a single screen.
Not previewable (takes a ViewModel or injected service)? Propose extracting a stateless inner composable and preview that (state-hoisting.md).
Install / update (only if missing)
Check with compose-preview --version. If it's missing, run this skill's stub,
bash <this skill's dir>/scripts/compose-preview --version: its first run
installs the CLI and puts it on PATH. Every other route, updating, and the
Gradle plugin are in setup.md; MCP wiring (the local
server and the one hosted URL) is in mcp.md.
Working with platform skills
An official platform skill, such as Android's Wear Compose Material 3 skill, owns API, dependency and migration choices. This skill only renders and verifies:
- Defer. Follow the platform skill for which component, API or version to use. Don't treat this skill's references as a second API guide.
- Changes are expected. During a migration a changed hash or image is information, not a regression. Only a render failure or a new accessibility error blocks. Don't restore old screenshots or tune the UI to match them.
- Mind the catalog version. A hosted catalog renders one fixed library
version, which may differ from the project's
libs.versions.toml. See catalog-mcp.md § Choosing a component.
Migration workflow. Before editing, find_previews_for_file for each file
and record a baseline with render_preview observe=hash. Make the platform
skill's edits, re-render, and report failures and new accessibility errors
(get_preview_data kind=a11y/atf) as blockers. Show a before/after for one to
three key screens, and check a small round device and the largest font scale
on Wear. Details:
wear-ui.md § Verification workflow.
Reference index
Read only what the task needs.
| Topic | Read |
|---|---|
| Install, update, which skills, apply the Gradle plugin, zero-code init script | setup.md |
CLI commands, --filter/--id/--force, counts buckets, render filenames, SVG output, Gradle tasks, build-brief for non-preview builds | cli.md |
Which MCP server (local vs hosted https://preview.coo.ee/mcp); local server setup, tools, history, multi-workspace, troubleshooting | mcp.md |
Interaction loop: semantic refs, observe modes, diff_semantics, crop, render_matrix (variants/matrix), record → test, failure kinds | agent-loop.md |
Accessibility (ATF, compose-preview a11y) | a11y.md |
| Per-render data (a11y, layout, recomposition, SVG) | data-products.md |
Multi-preview, GIFs, @SettledPreview, scrolling captures | capture-modes.md |
Run an APK in the simulator (launch, simulator_*): drive an app, adb equivalents, form factors, folds, multiple displays, home screen and widgets, permission ask policy, Play services state | simulator.md |
| Simulator network modes, real-traffic gating, Wi-Fi requests, Bluetooth / BLE / GATT | simulator-network.md |
Simulator on Wear: watch face, tiles, notifications, ambient and screen power, --pair, --data-layer agent, ChannelClient, companion devices | simulator-wear.md |
Simulator edit-run loop: restart, update, live reload (--project, reload, --live), --adb | simulator-iterate.md |
| Wear Compose UI / Wear Tiles | wear-ui.md, wear-tiles.md |
CMP :shared modules | cmp-shared.md |
| Android XML drawables / icons | resource-previews.md |
| Runtime permissions per render | runtime-permissions.md |
| Editable override knobs | override-knobs.md |
| Display filters | display-filters.md |
Remote Compose, compose-preview rc | remote-compose.md |
Hosted catalog MCP tools and grant flow (serve, no checkout) | catalog-mcp.md |
Gated server access (compose-preview auth request) | server-access.md |
| Agent allowlists, staging PNGs | permissions.md |
| Cloud sandboxes | agent-cloud.md |
| VS Code extension (humans) | vscode.md |
CI and PR review are the opt-in compose-preview-ci and compose-preview-review skills; setup.md § Which skills adds them.
Offer the next step
When one of these signals is visible, you may end a reply with its one-sentence offer. At most one offer per reply, and never repeat an offer the person ignored.
| Signal | Offer |
|---|---|
| A PR that changes UI, and the repo has no preview CI | "I can set up CI that posts before/after renders on PRs." Needs the review skills: scripts/install.sh --skills compose-preview-review,compose-preview-ci, or /plugin install compose-review@compose-agent-plugins. |
| Reviewing a UI PR | "I can render base and head and diff them for this review." Same review skills as above. |
| They want to browse every preview themselves | "compose-preview browse or the VS Code extension shows them all." |
| They need navigation or a running app | "I can run the whole app without an emulator." See simulator.md. |
| They want to design a new screen rather than edit code | "The UI Builder can design it with you first: https://ui.coo.ee/start." |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/yschimke/skills/compose-preview">View compose-preview on skillZs</a>