How to use the Manage Stitch Design Systems agent skill

What does the skill make the agent do?

The skill turns a project's visual style into a single source of truth for Google Stitch. That source is a DESIGN.md file describing colours, fonts, roundness and similar rules. Once the design system exists in Stitch, the tokens are held at project level, so later generation prompts do not need to repeat them.

The agent can work from two starting points. If the project already has screens, it reads them through the Stitch MCP tools and extracts a design system. If the project is new or you give a plain-language description, such as dark theme, blue and purple, rounded, Inter font, it maps those words to concrete hex codes, font families and roundness values and writes the DESIGN.md file. It also keeps a small .stitch/metadata.json file in sync with the project.

• Retrieve a project, its screens and their assets from Stitch
• Generate .stitch/DESIGN.md from existing screens or a written description
• Upload DESIGN.md and create the design system in Stitch
• Apply the design system to existing screens
• Record the project ID, title, screens and design system summary in .stitch/metadata.json

Install the skill from the ZIP or the Claude apps

Option one is a local install. Download the ZIP from this page and unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder to limit it to that project. Start a new agent session afterwards so the skill is picked up.

Option two is the Claude apps. Upload the ZIP under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills

What you need before you start

The skill depends on several things outside its own files. Check each one before you ask the agent to create a design system.

The skill references the stitch-utilities plugin, specifically its design-md and generate-design skills. These are not included in the files this page provides, so the skill will not fully work without them.

• A Google Stitch account and API key
• Stitch MCP tools, including list_projects, list_screens, get_screen, get_project, list_design_systems, create_design_system_from_design_md and apply_design_system
• Python 3, to run the upload_to_stitch.py script
• Access to the stitch-utilities plugin (design-md and generate-design skills)

How to ask the agent to use it

You do not need a special command. Describe the outcome in plain language and mention Stitch and the design system. The skill's description covers managing design systems in Stitch, retrieving assets, creating or updating design systems and applying them to screens, so requests of that kind are the ones it fits.

Examples of requests that match the skill's purpose:

• Create a design system in my Stitch project from this brief: dark theme, blue and purple, rounded corners, Inter font.
• Read the screens in my Stitch project and extract a design system from them.
• Apply the existing design system to the Home and Settings screens in this Stitch project.
• Update the design system in .stitch/DESIGN.md and sync it to Stitch.

Walk through the upload with approval

Before anything is uploaded, the skill requires a checkpoint. The agent must present a summary of the design system it is about to create, covering the display name, key colours, fonts and roundness, and wait for your explicit approval. It must not upload until you confirm.

Once you approve, the preferred method is the upload_to_stitch.py script. It base64-encodes the markdown in-process and sends it to the Stitch API. The script returns a sourceScreen ID and a screenInstance ID. The agent then calls create_design_system_from_design_md with the project ID and the selected screen instance. The skill also lists a direct upload_design_md MCP tool for DESIGN.md files under about 5KB, but the script is recommended.

• Set --generated-by to the calling skill name, such as stitch::code-to-design, or to the agent name, such as Claude Code. If you omit it, the script defaults to UserUploadedDesignMd.
• Read the summary carefully at the checkpoint before you approve.

Apply the design system to screens

To apply a design system to existing screens, the agent calls apply_design_system. The request must include only the id and sourceScreen of each selected screen instance. Position and size fields such as x, y, width and height cause the request to fail with an invalid argument error.

The agent gets the screen instance IDs from get_project and the design system's assetId from list_design_systems. Instances marked as DESIGN_SYSTEM_INSTANCE are filtered out, so only real screens are passed.

• Use get_project to list screenInstances
• Use list_design_systems to find the name in the form assets/{assetId}
• Skip any instance with type DESIGN_SYSTEM_INSTANCE

Keep .stitch/metadata.json in sync

After writing .stitch/DESIGN.md, the agent creates or updates .stitch/metadata.json. It records the projectId, the title, all known screens and a summary of the design system. Look at examples/metadata.json in the skill folder to see the expected format. For the full designSystem object and its options, see reference/tool-schema.md.

Safety notes: scripts and network access

This skill runs scripts and uses the network. The upload script sends DESIGN.md content to Google's Stitch API, so do not use it on projects whose design files must stay offline. The skill's allowed tools include Bash, Read, Write, web_fetch and the Stitch tools, so review the actions the agent proposes.

The approval checkpoint is part of the design. Do not configure the agent to skip it, because an upload without review would send design data to Stitch without your sign-off. The API key is passed on the command line in the example, so keep it out of shared logs and shared files.

• Never skip the user confirmation before upload
• Do not use the upload script for offline-only projects
• Check that the API key is not committed to version control