What is the upload-to-stitch skill?
The upload-to-stitch skill exists because a model cannot push even a small file through MCP: base64 encoding exceeds its output limit of roughly 16K tokens. The skill runs a Python script that reads the file and posts it to Stitch over HTTP, after you approve the file list.
It sits in the stitch-design plugin. Its description says to use it for any visual asset, HTML page or design document going into Stitch, especially when direct MCP calls fail or truncate.
The SKILL.md gives the reason plainly. Base64 encoding of even a small file is larger than the roughly 16K token output limit of the model, so the script reads the file itself and sends it directly over HTTP.
The three steps
- Identify the target project. The agent calls list_projects to find the right project ID.
- Get the API key. The agent looks in your active MCP server configuration, and if it cannot find or open it, it must ask you for the Stitch API key rather than continue.
- Run the script. First the agent shows you the file paths, sizes and types and waits for explicit approval.
Supported files and script options
| Extension | Sent as |
|---|---|
| png | image/png |
| jpg, jpeg | image/jpeg |
| webp | image/webp |
| html, htm | text/html |
| md | text/markdown |
The script detects the type from the extension. It requires a project ID, a file path and an API key, and accepts optional api-url, title and generated-by values.
Who the upload-to-stitch skill is for
Best for
- Anyone bringing a mockup, screenshot or exported page into a Stitch project.
- Workflows that need a design document, HTML page or visual asset uploaded into Stitch.
- Route-based uploads, where the title argument is set to a path such as /inbox.
Not for
- Creating screens from text. The generate-design skill handles prompts, and enhance-prompt sharpens them first.
- Formats beyond the five listed types.
- Setups where you cannot supply a Stitch API key. Related: design-md.
Use it with UiChemy
This skill moves files into Stitch, not into WordPress. For a design that should become a WordPress site, UiChemy can build from Figma, Composer or AI to WordPress. Click Get Started on uichemy.com. Related: image-to-code.
How to install Upload to Stitch Skill: Send Images, HTML and Markdown to a Project
npx plugins add google-labs-code/stitch-skills --scope project --target claude-codeConnect the Stitch MCP server
Finish the setup at https://stitch.withgoogle.com/docs/mcp/setup/ so list_projects works and the agent can find your project ID.
Install the plugin
For Claude Code, run
npx plugins add google-labs-code/stitch-skills --scope project --target claude-code. For Cursor, use--scope workspace --target cursor. The skill is part of stitch-design.Codex marketplace route
Run
codex plugin marketplace add google-labs-code/stitch-skills --ref main, then install stitch-design from it.Check Python
The script runs with python3. On macOS, if a certificate error appears, install certifi with pip or set SSL_CERT_FILE as the SKILL.md describes.
Ask for an upload
Use a request like the README's, asking to upload a local HTML file to a named Stitch project.
Check that it loaded
Ask the agent to upload a small PNG. It should list your projects, show the file path, size and type for your approval, then run upload_to_stitch.py and report the new screen.
Key features
- Bypasses the MCP token limitThe script reads the file and sends it over HTTP, since base64 of even a small file exceeds the roughly 16K token output limit.
- Five file typesPNG, JPEG, WebP, HTML and Markdown are supported, with the MIME type detected from the file extension.
- Approval before uploadA checkpoint requires the agent to present the paths, sizes and types of the files and wait for your explicit approval.
- API key handlingThe agent reads the key from your MCP server setup, and if it cannot, the SKILL.md says it must ask you and must not proceed without a valid key.
- Required optionsThe project-id, file-path and api-key options are required. api-url defaults to the Stitch API address.
- Route-path titlesFor HTML extracted from a web app, the title option should be the route path, such as /dashboard or /settings/profile.
- Generated-by labelThe generated-by option records how the file was made, for example the extract-static-html skill or the name of your agent.
- macOS certificate fixThe script tries the certifi package for root certificates, and a SSL_CERT_FILE variable can point to the certifi bundle if verification fails.
Frequently asked questions
Why does this skill use a script instead of an MCP tool?
The SKILL.md explains that a model cannot upload files through MCP tools directly, because the base64 encoding of even a small file exceeds its output limit of about 16K tokens. The script reads the file from disk and sends it straight over HTTP, so size is not limited by the model.
Which file types can I upload?
PNG, JPEG, WebP, HTML and Markdown. The script matches .png, .jpg, .jpeg, .webp, .html, .htm and .md extensions to image, text/html and text/markdown types automatically, so you only pass the file path.
How do I install the upload-to-stitch skill?
Register the Stitch MCP server, then run the repository's plugin install, for example npx plugins add google-labs-code/stitch-skills with a project scope and your agent as the target. Codex users add the repo as a plugin marketplace. It ships in stitch-design.
Where does the API key come from?
The agent finds it in your MCP server configuration for the agent you use. If it cannot find the key or cannot open the files, the SKILL.md says it must ask you to provide the Stitch API key, and it must not continue without a valid one.
Will it upload without asking?
No. Before running the script, the agent must pause, list the files with their paths, sizes and types, and wait for your explicit approval. The SKILL.md says not to execute the upload until you confirm.
What should I put in the title option?
For HTML extracted from a web app, use the route path of the page, such as /dashboard, /settings/profile or /inbox. The screen name in Stitch then identifies the route. For other uploads the title is optional.
What do I do about a certificate verification error?
On macOS the Python install may lack root certificates. The script tries the certifi package if it is installed. Otherwise install certifi with pip, or set the SSL_CERT_FILE environment variable to the certifi bundle path when you run the script.