How to Upload Local Assets and Mockups to Stitch Projects: Complete Guide

Use the stitch::upload-to-stitch skill to invoke a Python script that Base64-encodes local files and transmits them directly to the Stitch BatchCreateScreens REST endpoint, bypassing the model's ~16K token output limit that would otherwise truncate large assets.

The stitch::upload-to-stitch skill provides the canonical method to upload local assets and mockups to Stitch projects within the google-labs-code/stitch-skills ecosystem. This tool handles images, HTML mockups, and design markdown files by delegating the heavy lifting to a dedicated Python helper rather than attempting to process file contents through model outputs. By calling the Stitch API directly, the skill ensures reliable uploads regardless of file size, integrating seamlessly with the broader design system pipeline.

Why Direct API Upload Matters

Model outputs are constrained to approximately 16,000 tokens, while even modest PNG files require over 70,000 characters when Base64-encoded. The upload_to_stitch.py script located at plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py solves this bottleneck by executing the upload outside the model context. It reads the local file, encodes it to Base64, and POSTs the payload to the Stitch BatchCreateScreens endpoint at https://stitch.googleapis.com/v1/projects/<projectId>/screens:batchCreate.

Prerequisites for Uploading Local Assets

Before executing an upload, you must complete three preparation stages:

1. Locate the target project – Use the list_projects tool to retrieve the projectId of the Stitch project you want to augment.
2. Obtain a valid API key – The script requires an X-Goog-Api-Key header value. Extract this from MCP configuration files such as .gemini/antigravity/mcp_config.json, ~/.gemini/settings.json, or ~/.claude.json as listed in the skill documentation. If the key is unavailable, prompt the user to supply it manually.
3. Verify file accessibility – Ensure the target file exists at the specified local path and is readable by the script.

Technical Implementation of the Upload Script

The Python utility implements a three-stage pipeline to transform local files into Stitch screens.

MIME Type Detection

The script maps file extensions to MIME types using the _MIME_TYPES dictionary (lines 48-57 of upload_to_stitch.py). This mapping determines whether the upload becomes a DOCUMENT screen (HTML/Markdown) or an IMAGE screen (PNG, JPG, etc.).

Screen Request Construction

The build_screen_request function (lines 29-77) constructs the CreateScreenRequest payload. For HTML and Markdown uploads, it adds optional title and generatedBy metadata fields to track the source of the design asset.

API Execution

The call_batch_create_screens function (lines 66-94) handles the HTTP POST to the Stitch API. It includes the Base64-encoded file data and respects the optional createScreenInstances flag to generate displayable screen instances immediately upon upload.

Uploading Assets to Stitch Projects

Execute the script using the command template defined in plugins/stitch-design/skills/upload-to-stitch/SKILL.md. The CLI requires --project-id, --file-path, and --api-key parameters, with optional --title or --generated-by flags for metadata.

Upload a PNG Screenshot

python3 plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
  --project-id 1234567890 \
  --file-path ./assets/homepage.png \
  --api-key AIzaSyExampleKey \
  --title "Homepage Screenshot"

Upload an HTML Mockup

python3 plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
  --project-id 1234567890 \
  --file-path ./mockups/checkout.html \
  --api-key AIzaSyExampleKey \
  --generated-by "stitch::extract-static-html"

Upload a Design Markdown File

python3 plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
  --project-id 1234567890 \
  --file-path .stitch/DESIGN.md \
  --api-key AIzaSyExampleKey \
  --title "App Design System"

SSL Certificate Configuration

The script attempts to load the system CA bundle via the certifi Python package. On macOS or systems with custom certificate stores, set the SSL_CERT_FILE environment variable manually to point to your certificate authority bundle if the default resolution fails.

Summary

• The stitch::upload-to-stitch skill uses upload_to_stitch.py to bypass model token limits by calling the Stitch API directly.
• Files are Base64-encoded and sent to the BatchCreateScreens endpoint at https://stitch.googleapis.com/v1/projects/<projectId>/screens:batchCreate.
• The script auto-detects MIME types via the _MIME_TYPES dictionary (lines 48-57) to create either IMAGE or DOCUMENT screens.
• The build_screen_request function (lines 29-77) handles payload construction, while call_batch_create_screens (lines 66-94) executes the HTTP POST.
• Required parameters include projectId, file-path, and X-Goog-Api-Key extracted from MCP configuration files.

Frequently Asked Questions

What file types can I upload to Stitch projects?

The script supports images (PNG, JPEG) that become IMAGE screens, and HTML or Markdown files that become DOCUMENT screens. The MIME type is automatically detected from the file extension using the _MIME_TYPES mapping defined at lines 48-57 of upload_to_stitch.py.

Why can't I paste Base64 data directly into the model?

Model outputs are limited to approximately 16,000 tokens, while Base64-encoded images often exceed 70,000 characters. The Python script bypasses this limitation by executing the upload outside the model context and calling the Stitch REST API directly via the call_batch_create_screens function.

Where do I find the Stitch API key?

The X-Goog-Api-Key is stored in MCP configuration files such as .gemini/antigravity/mcp_config.json, ~/.gemini/settings.json, or ~/.claude.json. If the script cannot locate these files, you must provide the key manually via the --api-key parameter.

How does the script handle different screen types?

The build_screen_request function (lines 29-77) inspects the MIME type to determine screen classification. HTML and Markdown files receive DOCUMENT typing with optional title and generatedBy metadata, while images receive IMAGE typing, all configured in the CreateScreenRequest payload sent to the BatchCreateScreens endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}