How to use the Upload to Stitch agent skill (setup and tips)

What the Upload to Stitch skill makes the agent do

An agent skill is a folder with a SKILL.md instruction file and optional scripts that an AI agent can load when a task matches it. This skill covers uploading local assets to Stitch. The source explains that the model cannot upload files through MCP tools directly, because the base64 encoding of even a small file exceeds the model's output token limit (about 16K tokens).

Instead, the agent runs a bundled Python script, scripts/upload_to_stitch.py. The script reads the file and sends it directly over HTTP to the Stitch API. Supported files are PNG, JPG/JPEG and WebP images, HTML/HTM pages, and markdown (.md) files.

How to install the Upload to Stitch skill

Download the skill ZIP from the skill's page in this directory and unzip it. Then place the folder in one of these locations, depending on how you use your agent:

Use the personal Claude Code skills folder, ~/.claude/skills/, so the skill is available in every project. Or use a single project's .claude/skills/ folder so it applies only there. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills

What you need before uploading

You need Python 3, a Stitch project ID, and a Stitch API key. The source says the API key can be taken from an existing MCP configuration, such as Claude Code, Gemini CLI or Antigravity. The optional certifi Python package is needed on some macOS setups for SSL certificate verification.

To find the project ID, the agent uses list_projects. To find the API key, the agent reads the MCP config file for your tool. If it cannot find a key or cannot access those files, it must ask you to provide one and will not proceed without it.

• Python 3
• A Stitch project ID (the agent can look it up with list_projects)
• A Stitch API key, from an existing MCP configuration or supplied by you
• Optional: the certifi Python package

How to trigger the skill with natural requests

You do not need to type the skill name. Ask for an upload in plain language when you want visual assets, HTML pages or design docs in Stitch. The skill is written to activate especially when direct MCP tool calls fail or truncate.

Before running the upload, the agent must stop, list the files to be uploaded with their paths, sizes and types, and wait for your explicit approval. Nothing is sent until you confirm.

• "Upload this mockup PNG to my Stitch project."
• "Send the extracted HTML pages from my web app to Stitch, one screen per route."
• "Add these design notes in markdown to the Stitch project."
• "The direct Stitch upload keeps truncating this file. Upload it with the script instead."

Run the upload script and set the options

The agent runs the script with the command below. The script auto-detects the MIME type from the file extension. Only --project-id, --file-path and --api-key are required.

Use --title to set the screen title. For extracted HTML from a web app, the source recommends setting it to the route path, such as '/dashboard', '/settings/profile' or '/inbox', so each screen in Stitch is clearly identified. --generated-by records how the file was made, for example 'stitch::extract-static-html' skill, 'Claude Code', 'Codex' or 'Gemini'. If you omit --api-url, the default is https://stitch.googleapis.com.

• --project-id: required, the Stitch project ID
• --file-path: required, path to the local file
• --api-key: required, Stitch API key
• --api-url: optional, defaults to https://stitch.googleapis.com
• --title: optional, screen title (use the route path for web app HTML)
• --generated-by: optional, how the file was generated

Fix SSL certificate errors on macOS

If the upload fails with ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] unable to get local issuer certificate, your Python installation lacks configured root certificate authorities. The script tries the certifi package automatically if it is installed. If it is not, install it with pip or point the SSL_CERT_FILE environment variable at the certifi bundle when running the script.

• Install certifi: pip install certifi
• Or set SSL_CERT_FILE for a single run, as shown in the code block

Safety notes: scripts, network and your API key

This skill runs a script and uses the network. The agent reads local MCP config files to find your API key, so if you do not want an agent reading those files, do not use this skill. Once you approve, the contents of the files are sent over the network to the Stitch API, so do not upload sensitive or confidential files.

Check the file list the agent shows you before approving. Confirm the paths, sizes and types match what you intended to send.

• The skill runs scripts/upload_to_stitch.py with Python.
• The agent reads Antigravity, Gemini CLI and Claude Code config files to find the API key.
• File contents leave your machine once you approve the upload.
• The skill only targets Stitch projects.