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
- Check for the fetch script — Verify
scripts/fetch-stitch.sh exists. If not, create it (simple curl wrapper with redirect handling).
- Check existing cache — Read
.stitch/designs/ to see what's already downloaded. Avoid re-downloading unless the user specifies "refresh".
- 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"):
- Call
mcp__stitch__list_projects (and optionally with filter: "view=shared" if user asked for shared).
- Present a table:
## Stitch Projects
| # | Project Title | Project ID | Screens |
|---|--------------|------------|---------|
| 1 | Homepage Explorations | 12345 | 6 |
| 2 | Dashboard V2 | 67890 | 14 |
| ... | ... | ... | ... |
- Ask the user which project(s) to download.
If project ID provided:
- Call
mcp__stitch__get_project to verify it exists and get the title.
- Proceed to Phase 2.
Phase 2 — Inventory Screens
- Call
mcp__stitch__list_screens with the selected project ID.
- For each screen, extract:
name (resource name), title, deviceType, width, height.
- 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)
- 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:
Call mcp__stitch__get_screen with the screen's resource name to get download URLs, dimensions, and full metadata.
Check local cache — if {project-slug}/{screen-slug}.html already exists and user didn't specify "refresh", skip. Report as "cached".
Download HTML:
bash scripts/fetch-stitch.sh "{htmlCode.downloadUrl}" ".stitch/designs/{project-slug}/{screen-slug}.html"
Download screenshot — append =w{width} to the screenshot URL for full resolution:
bash scripts/fetch-stitch.sh "{screenshot.downloadUrl}=w{width}" ".stitch/designs/{project-slug}/{screen-slug}.png"
Save screen metadata:
{
"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"
}
Save project metadata (once per project) as _project.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:
- Each card has a ✕ button in the top-right corner
- Clicking it archives the screen — card dims to 35% opacity, grayscales the thumbnail, and shows an "ARCHIVED" label
- A toast notification appears with an Undo button (4-second window)
- Archived cards are hidden by default — click Show Archived in the controls to reveal them
- Archived screens can be restored with the ↩ button
- State persists in
localStorage across page reloads
- 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:
- Read all
_project.json files in .stitch/designs/*/ to get project metadata.
- Read all
*.meta.json files in each project directory to get screen metadata.
- Sort projects alphabetically by title.
- Within each project, sort screens by: device type (DESKTOP first) then title alphabetically.
- Populate the template with actual data.
- Write to
.stitch/designs/index.html.
Phase 5 — Report
## 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.
1---2name: stitch-download3description: "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."4user-invocable: true5allowed-tools: Read, Write, Edit, Bash, Grep, Glob, mcp__stitch__list_projects, mcp__stitch__list_screens, mcp__stitch__get_screen, mcp__stitch__get_project6metadata:7 source: https://skillmd.com/skills/joshuashepherd/stitch-download8---910Download and organize Stitch project designs for browser viewing: $ARGUMENTS1112$ARGUMENTS should include:13- A Stitch project ID, OR "list" to browse all projects14- Optionally: "shared" to include projects shared with you (default: owned only)15- Optionally: a specific screen ID or screen title to download a single screen16- Optionally: "refresh" to re-download screens that already exist locally17- Empty — list all projects and ask the user which to download1819---2021## Purpose2223This 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`.2425## Before Starting26271. **Check for the fetch script** — Verify `scripts/fetch-stitch.sh` exists. If not, create it (simple curl wrapper with redirect handling).282. **Check existing cache** — Read `.stitch/designs/` to see what's already downloaded. Avoid re-downloading unless the user specifies "refresh".293. **Ensure `.stitch/` is gitignored** — Check `.gitignore` for `.stitch/` entry. Add it if missing (these are large binary/HTML files).3031---3233## Phase 1 — Inventory Projects3435### If no project ID provided (or "list"):361. Call `mcp__stitch__list_projects` (and optionally with `filter: "view=shared"` if user asked for shared).372. Present a table:3839```40## Stitch Projects4142| # | Project Title | Project ID | Screens |43|---|--------------|------------|---------|44| 1 | Homepage Explorations | 12345 | 6 |45| 2 | Dashboard V2 | 67890 | 14 |46| ... | ... | ... | ... |47```48493. Ask the user which project(s) to download.5051### If project ID provided:521. Call `mcp__stitch__get_project` to verify it exists and get the title.532. Proceed to Phase 2.5455---5657## Phase 2 — Inventory Screens58591. Call `mcp__stitch__list_screens` with the selected project ID.602. For each screen, extract: `name` (resource name), `title`, `deviceType`, `width`, `height`.613. Present a screen inventory:6263```64## Screens in "[Project Title]"6566| # | Screen Title | Device | Dimensions | Cached? |67|---|-------------|--------|------------|---------|68| 1 | Homepage Hero | DESKTOP | 2560×4200 | No |69| 2 | Homepage Mobile | MOBILE | 390×2800 | Yes |70| ... | ... | ... | ... | ... |7172Download all N screens? (Y/n)73```74754. If the user confirms, proceed to Phase 3. If they select specific screens, note which ones.7677---7879## Phase 3 — Download & Organize8081### Directory structure82```83.stitch/designs/84 ├── {project-slug}/85 │ ├── _project.json # Project metadata86 │ ├── {screen-slug}.html # Full HTML source87 │ ├── {screen-slug}.png # Full-res screenshot88 │ ├── {screen-slug}.meta.json # Screen metadata89 │ └── ...90 ├── {another-project-slug}/91 │ └── ...92 └── index.html # Browseable gallery (generated in Phase 4)93```9495### Slug generation96- Project slug: project title → lowercase, spaces→hyphens, strip special chars. Example: "Homepage Explorations" → `homepage-explorations`97- Screen slug: screen title → lowercase, spaces→hyphens, strip parenthetical suffixes, strip special chars. Example: "Homepage: The Modern Archivist (Full)" → `homepage-the-modern-archivist`9899### For each screen:1001011. **Call `mcp__stitch__get_screen`** with the screen's resource name to get download URLs, dimensions, and full metadata.1021032. **Check local cache** — if `{project-slug}/{screen-slug}.html` already exists and user didn't specify "refresh", skip. Report as "cached".1041053. **Download HTML:**106 ```bash107 bash scripts/fetch-stitch.sh "{htmlCode.downloadUrl}" ".stitch/designs/{project-slug}/{screen-slug}.html"108 ```1091104. **Download screenshot** — append `=w{width}` to the screenshot URL for full resolution:111 ```bash112 bash scripts/fetch-stitch.sh "{screenshot.downloadUrl}=w{width}" ".stitch/designs/{project-slug}/{screen-slug}.png"113 ```1141155. **Save screen metadata:**116 ```json117 {118 "screenId": "projects/{project}/screens/{screen}",119 "title": "Homepage Hero",120 "width": 2560,121 "height": 4200,122 "deviceType": "DESKTOP",123 "projectId": "12345",124 "projectTitle": "Homepage Explorations",125 "fetchedAt": "2026-03-22T14:00:00Z"126 }127 ```1281296. **Save project metadata** (once per project) as `_project.json`:130 ```json131 {132 "projectId": "12345",133 "title": "Homepage Explorations",134 "screenCount": 6,135 "fetchedAt": "2026-03-22T14:00:00Z"136 }137 ```138139### Progress reporting140After each screen, report:141```142[3/6] ✓ Homepage Hero — 2560×4200 — 142KB HTML, 890KB PNG143```144145---146147## Phase 4 — Generate Gallery148149Create `.stitch/designs/index.html` — a self-contained HTML file (no external dependencies) that presents all downloaded screens as a browseable gallery.150151### Gallery features:152- **Project grouping** — screens organized under project headings153- **Thumbnail grid** — PNG screenshots displayed as cards in a responsive CSS grid154- **Screen metadata** — title, device type, dimensions shown on each card155- **Click to view** — clicking a thumbnail opens the full HTML file in a new tab156- **Click to view screenshot** — secondary link to open the full-res PNG157- **Filter by device** — simple toggle buttons for DESKTOP / MOBILE / TABLET158- **Search** — text filter across screen titles159- **Dark background** — designs display best on a neutral dark background160- **Timestamps** — show when each screen was fetched161- **Archive/hide screens** — each card has a ✕ button to archive it (dims + grays out the card, hides by default)162- **Show Archived toggle** — reveals archived screens so they can be restored with ↩163- **Undo** — toast notification with undo for every archive/restore action164- **Persistent state** — archive state saved in localStorage (survives page reload) and optionally in `_hidden.json`165- **Export list** — copies a text list of all archived screen titles + IDs to clipboard for manual Stitch cleanup166167### Gallery architecture:168169The gallery is a self-contained HTML file with these interactive features:170171**Archive/Hide workflow:**1721. Each card has a ✕ button in the top-right corner1732. Clicking it archives the screen — card dims to 35% opacity, grayscales the thumbnail, and shows an "ARCHIVED" label1743. A toast notification appears with an **Undo** button (4-second window)1754. Archived cards are hidden by default — click **Show Archived** in the controls to reveal them1765. Archived screens can be restored with the ↩ button1776. State persists in `localStorage` across page reloads1787. **Export List** copies all archived screen titles + keys to clipboard for manual Stitch cleanup179180**Filtering:**181- Device type toggles (All / Desktop / Mobile)182- Text search across screen titles183- Show/hide archived toggle with count badge184- Empty category groups auto-hide185186**Data flow:**187- `_manifest.json` (per project) — source of truth for screen metadata, generated during download188- `_hidden.json` (gallery root) — optional file-based persistence of archived screens (can be committed or shared)189- `localStorage['stitch-gallery-hidden']` — browser-side persistence, merged on load190191### Building the gallery:1921. Read all `_project.json` files in `.stitch/designs/*/` to get project metadata.1932. Read all `*.meta.json` files in each project directory to get screen metadata.1943. Sort projects alphabetically by title.1954. Within each project, sort screens by: device type (DESKTOP first) then title alphabetically.1965. Populate the template with actual data.1976. Write to `.stitch/designs/index.html`.198199---200201## Phase 5 — Report202203```markdown204## Stitch Download Complete205206### Summary207- **Projects:** {count}208- **Screens downloaded:** {count} ({count} new, {count} cached)209- **Total size:** ~{size}210211### Projects212| Project | Screens | Directory |213|---------|---------|-----------|214| {title} | {count} | `.stitch/designs/{slug}/` |215| ... | ... | ... |216217### Gallery218Open in browser: `.stitch/designs/index.html`219220```bash221open .stitch/designs/index.html222```223224### Next Steps225- Browse the gallery to review designs226- Use `/stitch-react {projectId} {route}` to convert a screen to React components227- Re-run `/stitch-download {projectId} refresh` to update with new screens228```229230---231232## Rules233234- **Never modify project source code.** This skill only writes to `.stitch/designs/`.235- **Always use `scripts/fetch-stitch.sh`** for downloads. AI built-in fetch fails on Google Cloud Storage signed URLs.236- **Never re-download cached screens** unless the user specifies "refresh". Check for existing files first.237- **Keep the gallery self-contained** — no CDN links, no external CSS/JS. Everything inline in one HTML file.238- **Preserve existing gallery state** — when downloading a new project, merge into the existing gallery rather than overwriting screens from other projects.239- **Handle download failures gracefully** — if a screen fails to download, log it, continue with the next, and include the failure in the report.240- **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.