---
name: stitch
description: Operate Google Stitch through an already configured Stitch MCP server. Use when the user explicitly mentions Stitch or asks to generate, edit, vary, import, export, synchronize, or convert Stitch screens; manage a Stitch design system; run a resumable multi-page Stitch loop; or turn Stitch screens into React. Do not trigger for generic UI design requests that do not require Stitch.
---

# Stitch

Treat Stitch as a design execution backend. Keep product structure, visual direction, and design policy in Aphrodite; use this skill to translate those decisions into Stitch operations and code artifacts.

## Boundary

- Let `design-plan` (`/aphrodite`) own discovery, IA, layout blueprints, and the root `DESIGN.md`.
- Let Stitch own remote project/screen operations and `.stitch/` runtime state.
- Let the existing application architecture own routing, state, data, and component conventions.
- Use standalone Stitch mode only when the user explicitly wants direct Stitch work without Aphrodite.

Never invent a visual direction inside this skill when `DESIGN.md` or `docs/design-refs/` exists. Compile those artifacts into Stitch inputs.

## Preflight

1. Inspect the available tools and identify the Stitch MCP namespace by capability, not by a hard-coded prefix.
2. Stop and report the missing dependency if no Stitch MCP tools are available. Never fabricate project IDs, screen IDs, URLs, or tool results.
3. Read [references/mcp-contract.md](references/mcp-contract.md) completely before any Stitch MCP call.
4. Read the project root `DESIGN.md` and relevant `docs/design-refs/` artifacts before generating or editing a screen.
5. Check `.stitch/metadata.json` before remote lookup. Validate it with:

```bash
python <STITCH_SKILL_DIR>/scripts/validate_stitch_state.py .stitch/metadata.json
```

Resolve `<STITCH_SKILL_DIR>` to the directory containing this `SKILL.md`; do not assume the skill is installed inside the target project.

6. Classify the action:
   - Read-only: list/get projects, retrieve screens, download artifacts, compare state.
   - Remote mutation: create/edit/vary/apply a design system.
   - Sensitive upload: send a local image, HTML file, or `DESIGN.md` to Stitch.
7. Treat the user's explicit request to create/edit/vary as authorization for that scoped remote mutation. Before a sensitive upload, still show the exact project, files, types, and sizes and obtain confirmation.

## Route the Request

| Invocation | Route | Required reference |
|---|---|---|
| `/stitch generate` | Generate a screen from text or an uploaded image | [generate-and-design-system.md](references/generate-and-design-system.md) |
| `/stitch edit` | Modify selected existing screens | [generate-and-design-system.md](references/generate-and-design-system.md) |
| `/stitch variants` | Produce controlled alternatives from a selected screen | [generate-and-design-system.md](references/generate-and-design-system.md) |
| `/stitch design-system pull` | Reverse-extract remote visual language into a proposed `DESIGN.md` update | [generate-and-design-system.md](references/generate-and-design-system.md) |
| `/stitch design-system push` | Synchronize the root `DESIGN.md` into Stitch | [generate-and-design-system.md](references/generate-and-design-system.md) |
| `/stitch design-system apply` | Apply a Stitch design-system asset to selected screens | [generate-and-design-system.md](references/generate-and-design-system.md) |
| `/stitch loop` | Generate a resumable multi-page set | [loop-state.md](references/loop-state.md) |
| `/stitch react` | Convert or synchronize Stitch screens with a React app | [react-handoff.md](references/react-handoff.md) |
| `/stitch import` | Capture local UI and upload it into Stitch | [import-export.md](references/import-export.md) |
| `/stitch sync` | Refresh remote metadata and local staged artifacts | [loop-state.md](references/loop-state.md) |
| `/stitch status` | Compare local runtime state with the remote project | [loop-state.md](references/loop-state.md) |

Preserve these compatibility aliases:

- `/stitch design` means `/stitch design-system pull`.
- `/stitch prompt` means compile an Aphrodite brief into a `/stitch generate` request without calling Stitch unless generation was requested.

If the request is ambiguous, infer the least-mutating route from the available artifacts. Ask only when two routes would materially change different remote state.

## Artifact Authority

Use this order when artifacts disagree:

1. Root `DESIGN.md`: design-system source of truth.
2. Latest `docs/design-refs/` brief, sitemap, direction, and layout blueprint: page structure and content contract.
3. Existing application code: functional and architectural contract.
4. `.stitch/` files: transport, cache, and resumable execution state.
5. Remote Stitch screen: generated implementation candidate.

Use `.stitch/DESIGN.md` only as a synchronized transport copy of root `DESIGN.md`. Do not let it become a second independently edited design system. See [references/loop-state.md](references/loop-state.md) for the full artifact contract.

## Core Execution Protocol

1. Retrieve the current project and selected screens before mutation.
2. Resolve the intended device type, target screen instances, and design-system asset.
3. Compile only the requested change:
   - Generate for a new structure.
   - Edit for a localized change.
   - Create variants for exploration around a good base.
   - Avoid rerolling a screen whose structure is already correct.
4. Perform the smallest sufficient Stitch operation.
5. Retrieve the resulting project and screen metadata again; do not trust a mutation response alone.
6. Download the resulting HTML and full-width screenshot into `.stitch/designs/` without overwriting existing files unless refresh was requested.
7. View the screenshot and compare it with `DESIGN.md`, the layout blueprint, and the requested delta.
8. Update `.stitch/metadata.json` only from observed remote state, then run the state validator.
9. Run code-level and visual verification required by the selected route.
10. Report project ID, affected screen IDs, local artifacts, verification evidence, and any residual drift.

## Non-Negotiable Rules

- Never assume legacy tools such as `get_screen_html`, `get_screen_metadata`, or `download_screen_asset` exist. Discover the live contract and prefer `get_screen` download URLs when available.
- Never repeat colors, fonts, and theme instructions in every generation prompt when a project-level Stitch design system is applied. This creates two competing theme sources.
- Never send position or dimension fields to `apply_design_system`; pass only `id` and `sourceScreen` for real screen instances.
- Never expose an API key in a prompt, command transcript, committed file, or report. Use the `STITCH_API_KEY` environment variable for direct uploads.
- Never overwrite an existing root `DESIGN.md`, staged screen, or application file without first comparing the old and new state.
- Never keep an autonomous loop alive by inventing unnecessary pages. Finish when the declared roadmap is complete.
- Never impose a new React architecture merely because Stitch emitted static HTML. Adapt to the repository's stack and conventions.
- Never declare visual fidelity from HTML inspection alone. Inspect the downloaded screenshot or a rendered local page.

## Deterministic Helpers

Use the bundled scripts instead of re-emitting binary/base64 payloads or writing ad hoc state checks:

```bash
# Validate resumable state
python <STITCH_SKILL_DIR>/scripts/validate_stitch_state.py .stitch/metadata.json

# Download a screen artifact without accidental overwrite
python <STITCH_SKILL_DIR>/scripts/fetch_stitch_asset.py \
  --url "<download-url>" --output .stitch/designs/home.html

# Preview an upload without network mutation
python <STITCH_SKILL_DIR>/scripts/upload_to_stitch.py \
  --project-id "<project-id>" --file DESIGN.md --dry-run
```

Read [references/import-export.md](references/import-export.md) before using the uploader. An actual upload requires `STITCH_API_KEY` and `--confirm-upload` after user confirmation.

## Completion Evidence

Do not report completion until all applicable evidence exists:

- Stitch MCP capability and target project confirmed.
- Resulting screen or design-system IDs retrieved after mutation.
- `.stitch/metadata.json` updated and validator passed.
- Generated screenshot visually inspected.
- React route: typecheck/lint and rendered comparison completed when the project supports them.
- Loop route: sitemap and baton agree; baton is explicitly complete when no declared page remains.

## Provenance

This local adapter selectively incorporates operational patterns from `google-labs-code/stitch-skills` as reviewed at commit `535b0889a46868c9b08f8a7f7084db3c1958a2b6` on 2026-08-09. The upstream project is a useful implementation reference, not the local design-policy authority and not an officially supported Google product.