# Stitch Download > Browse Stitch projects, download all screens (HTML + screenshots), and generate an organized local gallery with an index.html for browser viewing. Use when reviewing designs before conversion, comparing screens, or sharing with stakeholders. - Skill: `joshuashepherd/stitch-download` (Agent Skill) - Install (CLI): `npx skillmds@latest add joshuashepherd/stitch-download` - Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/stitch-download/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/joshuashepherd/stitch-download --- Download and organize Stitch project designs for browser viewing: $ARGUMENTS $ARGUMENTS should include: - A Stitch project ID, OR "list" to browse all projects - Optionally: "shared" to include projects shared with you (default: owned only) - Optionally: a specific screen ID or screen title to download a single screen - Optionally: "refresh" to re-download screens that already exist locally - Empty — list all projects and ask the user which to download --- ## Purpose This skill connects to the Stitch MCP, inventories existing projects and screens, downloads all assets (HTML source + full-resolution screenshots), and generates a local browseable gallery at `.stitch/designs/index.html`. The gallery organizes screens by project with thumbnails, metadata, and links to full HTML previews — making it easy to review designs in the browser, share with stakeholders, or select screens for conversion with `/stitch-react`. ## Before Starting 1. **Check for the fetch script** — Verify `scripts/fetch-stitch.sh` exists. If not, create it (simple curl wrapper with redirect handling). 2. **Check existing cache** — Read `.stitch/designs/` to see what's already downloaded. Avoid re-downloading unless the user specifies "refresh". 3. **Ensure `.stitch/` is gitignored** — Check `.gitignore` for `.stitch/` entry. Add it if missing (these are large binary/HTML files). --- ## Phase 1 — Inventory Projects ### If no project ID provided (or "list"): 1. Call `mcp__stitch__list_projects` (and optionally with `filter: "view=shared"` if user asked for shared). 2. Present a table: ``` ## Stitch Projects | # | Project Title | Project ID | Screens | |---|--------------|------------|---------| | 1 | Homepage Explorations | 12345 | 6 | | 2 | Dashboard V2 | 67890 | 14 | | ... | ... | ... | ... | ``` 3. Ask the user which project(s) to download. ### If project ID provided: 1. Call `mcp__stitch__get_project` to verify it exists and get the title. 2. Proceed to Phase 2. --- ## Phase 2 — Inventory Screens 1. Call `mcp__stitch__list_screens` with the selected project ID. 2. For each screen, extract: `name` (resource name), `title`, `deviceType`, `width`, `height`. 3. Present a screen inventory: ``` ## Screens in "[Project Title]" | # | Screen Title | Device | Dimensions | Cached? | |---|-------------|--------|------------|---------| | 1 | Homepage Hero | DESKTOP | 2560×4200 | No | | 2 | Homepage Mobile | MOBILE | 390×2800 | Yes | | ... | ... | ... | ... | ... | Download all N screens? (Y/n) ``` 4. If the user confirms, proceed to Phase 3. If they select specific screens, note which ones. --- ## Phase 3 — Download & Organize ### Directory structure ``` .stitch/designs/ ├── {project-slug}/ │ ├── _project.json # Project metadata │ ├── {screen-slug}.html # Full HTML source │ ├── {screen-slug}.png # Full-res screenshot │ ├── {screen-slug}.meta.json # Screen metadata │ └── ... ├── {another-project-slug}/ │ └── ... └── index.html # Browseable gallery (generated in Phase 4) ``` ### Slug generation - Project slug: project title → lowercase, spaces→hyphens, strip special chars. Example: "Homepage Explorations" → `homepage-explorations` - Screen slug: screen title → lowercase, spaces→hyphens, strip parenthetical suffixes, strip special chars. Example: "Homepage: The Modern Archivist (Full)" → `homepage-the-modern-archivist` ### For each screen: 1. **Call `mcp__stitch__get_screen`** with the screen's resource name to get download URLs, dimensions, and full metadata. 2. **Check local cache** — if `{project-slug}/{screen-slug}.html` already exists and user didn't specify "refresh", skip. Report as "cached". 3. **Download HTML:** ```bash bash scripts/fetch-stitch.sh "{htmlCode.downloadUrl}" ".stitch/designs/{project-slug}/{screen-slug}.html" ``` 4. **Download screenshot** — append `=w{width}` to the screenshot URL for full resolution: ```bash bash scripts/fetch-stitch.sh "{screenshot.downloadUrl}=w{width}" ".stitch/designs/{project-slug}/{screen-slug}.png" ``` 5. **Save screen metadata:** ```json { "screenId": "projects/{project}/screens/{screen}", "title": "Homepage Hero", "width": 2560, "height": 4200, "deviceType": "DESKTOP", "projectId": "12345", "projectTitle": "Homepage Explorations", "fetchedAt": "2026-03-22T14:00:00Z" } ``` 6. **Save project metadata** (once per project) as `_project.json`: ```json { "projectId": "12345", "title": "Homepage Explorations", "screenCount": 6, "fetchedAt": "2026-03-22T14:00:00Z" } ``` ### Progress reporting After each screen, report: ``` [3/6] ✓ Homepage Hero — 2560×4200 — 142KB HTML, 890KB PNG ``` --- ## Phase 4 — Generate Gallery Create `.stitch/designs/index.html` — a self-contained HTML file (no external dependencies) that presents all downloaded screens as a browseable gallery. ### Gallery features: - **Project grouping** — screens organized under project headings - **Thumbnail grid** — PNG screenshots displayed as cards in a responsive CSS grid - **Screen metadata** — title, device type, dimensions shown on each card - **Click to view** — clicking a thumbnail opens the full HTML file in a new tab - **Click to view screenshot** — secondary link to open the full-res PNG - **Filter by device** — simple toggle buttons for DESKTOP / MOBILE / TABLET - **Search** — text filter across screen titles - **Dark background** — designs display best on a neutral dark background - **Timestamps** — show when each screen was fetched - **Archive/hide screens** — each card has a ✕ button to archive it (dims + grays out the card, hides by default) - **Show Archived toggle** — reveals archived screens so they can be restored with ↩ - **Undo** — toast notification with undo for every archive/restore action - **Persistent state** — archive state saved in localStorage (survives page reload) and optionally in `_hidden.json` - **Export list** — copies a text list of all archived screen titles + IDs to clipboard for manual Stitch cleanup ### Gallery architecture: The gallery is a self-contained HTML file with these interactive features: **Archive/Hide workflow:** 1. Each card has a ✕ button in the top-right corner 2. Clicking it archives the screen — card dims to 35% opacity, grayscales the thumbnail, and shows an "ARCHIVED" label 3. A toast notification appears with an **Undo** button (4-second window) 4. Archived cards are hidden by default — click **Show Archived** in the controls to reveal them 5. Archived screens can be restored with the ↩ button 6. State persists in `localStorage` across page reloads 7. **Export List** copies all archived screen titles + keys to clipboard for manual Stitch cleanup **Filtering:** - Device type toggles (All / Desktop / Mobile) - Text search across screen titles - Show/hide archived toggle with count badge - Empty category groups auto-hide **Data flow:** - `_manifest.json` (per project) — source of truth for screen metadata, generated during download - `_hidden.json` (gallery root) — optional file-based persistence of archived screens (can be committed or shared) - `localStorage['stitch-gallery-hidden']` — browser-side persistence, merged on load ### Building the gallery: 1. Read all `_project.json` files in `.stitch/designs/*/` to get project metadata. 2. Read all `*.meta.json` files in each project directory to get screen metadata. 3. Sort projects alphabetically by title. 4. Within each project, sort screens by: device type (DESKTOP first) then title alphabetically. 5. Populate the template with actual data. 6. Write to `.stitch/designs/index.html`. --- ## Phase 5 — Report ```markdown ## Stitch Download Complete ### Summary - **Projects:** {count} - **Screens downloaded:** {count} ({count} new, {count} cached) - **Total size:** ~{size} ### Projects | Project | Screens | Directory | |---------|---------|-----------| | {title} | {count} | `.stitch/designs/{slug}/` | | ... | ... | ... | ### Gallery Open in browser: `.stitch/designs/index.html` ```bash open .stitch/designs/index.html ``` ### Next Steps - Browse the gallery to review designs - Use `/stitch-react {projectId} {route}` to convert a screen to React components - Re-run `/stitch-download {projectId} refresh` to update with new screens ``` --- ## Rules - **Never modify project source code.** This skill only writes to `.stitch/designs/`. - **Always use `scripts/fetch-stitch.sh`** for downloads. AI built-in fetch fails on Google Cloud Storage signed URLs. - **Never re-download cached screens** unless the user specifies "refresh". Check for existing files first. - **Keep the gallery self-contained** — no CDN links, no external CSS/JS. Everything inline in one HTML file. - **Preserve existing gallery state** — when downloading a new project, merge into the existing gallery rather than overwriting screens from other projects. - **Handle download failures gracefully** — if a screen fails to download, log it, continue with the next, and include the failure in the report. - **Respect URL expiration** — Stitch signed URLs expire. If a download fails, note that the user may need to re-list screens to get fresh URLs.