diff --git a/README.md b/README.md
index 86a404e..94e15a3 100644
--- a/README.md
+++ b/README.md
@@ -104,9 +104,9 @@ Code generation, framework integration, and asset compilation from Stitch design
| Skill | Description | Prompt Example |
|---|---|---|
-| [stitch::react-components](plugins/stitch-build/skills/react-components/) | Convert Stitch screens to React component systems with automated validation and design token consistency | *"Convert all screens in Stitch project `projects/123` to React components."* |
+| [stitch::react-components](plugins/stitch-build/skills/react-components/) | Convert Stitch screens to React component systems with automated validation and design token consistency | · *"Convert all screens in Stitch project `projects/123` to React components."*
· *"Sync the app to the last updates of the Stitch project `13039335308618232534`."* |
+| [stitch::react-native](plugins/stitch-build/skills/react-native/) | Convert Stitch HTML designs to production-ready React Native components with StyleSheet and platform-specific code | · *"Convert the Stitch design to React Native components with proper theme and navigation."*
· *"Sync the app to the last updates of the Stitch project `13039335308618232534`."* |
| [remotion](plugins/stitch-build/skills/remotion/) | Generate walkthrough videos from Stitch projects using Remotion with smooth transitions and zooming | *"Generate a walkthrough video of the Stitch project `projects/456`."* |
-| [react-native](plugins/stitch-build/skills/react-native/) | Convert Stitch HTML designs to production-ready React Native components with StyleSheet and platform-specific code | *"Convert the Stitch design to React Native components with proper theme and navigation."* |
| [shadcn-ui](plugins/stitch-build/skills/shadcn-ui/) | Expert guidance for integrating and building applications with shadcn/ui components | *"Set up shadcn/ui and build a data table with sorting and filtering."* |
---
diff --git a/plugins/stitch-build/skills/react-components/SKILL.md b/plugins/stitch-build/skills/react-components/SKILL.md
index 1dece3f..95b6634 100644
--- a/plugins/stitch-build/skills/react-components/SKILL.md
+++ b/plugins/stitch-build/skills/react-components/SKILL.md
@@ -1,6 +1,9 @@
---
name: stitch::react-components
-description: Converts Stitch designs into modular Vite and React components using system-level networking and AST-based validation.
+description: >-
+ Converts Stitch designs into modular Vite and React components, or syncs/updates
+ existing React components to align with the latest Stitch designs, using system-level
+ networking and AST-based validation.
allowed-tools:
- "stitch*:*"
- "Bash"
@@ -11,46 +14,97 @@ allowed-tools:
# Stitch to React Components
-You are a frontend engineer focused on transforming designs into clean React code. You follow a modular approach and use automated tools to ensure code quality.
+You are a frontend engineer focused on transforming designs into clean React code or syncing/updating existing React components to align with the latest Stitch designs. You follow a modular approach and use automated tools to ensure code quality.
+
+> **CRITICAL: Every step in this skill is MANDATORY. Do NOT skip any step or take shortcuts. Each section contains a GATE that must be satisfied before proceeding.**
+
+## Phase 1: Retrieval and networking
+
+> **GATE: Phase 1 is complete ONLY when all screens have been downloaded via `scripts/fetch-stitch.sh` AND visually audited. Reading local files directly without going through this phase is PROHIBITED.**
-## Retrieval and networking
1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `stitch:`) for all subsequent calls.
-2. **Metadata fetch**: Call `[prefix]:get_screen` to retrieve the design JSON.
+2. **Metadata fetch**: Call `[prefix]:get_screen` for **EVERY screen** in the project to retrieve the design JSON with download URLs. Do NOT skip any screen.
3. **Check for existing designs**: Before downloading, check if `.stitch/designs/{page}.html` and `.stitch/designs/{page}.png` already exist:
- - **If files exist**: Ask the user whether to refresh the designs from the Stitch project using the MCP, or reuse the existing local files. Only re-download if the user confirms.
+ - **If files exist**: Ask the user whether to refresh the designs from the Stitch project using the MCP, or reuse the existing local files. **You MUST ask — do not assume.** Only re-download if the user confirms.
- **If files do not exist**: Proceed to step 4.
-4. **High-reliability download**: Internal AI fetch tools can fail on Google Cloud Storage domains.
+4. **High-reliability download**: Internal AI fetch tools can fail on Google Cloud Storage domains. You MUST use the provided script.
- **HTML**: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" ".stitch/designs/{page}.html"`
- - **Screenshot**: Append `=w{width}` to the screenshot URL first, where `{width}` is the `width` value from the screen metadata (Google CDN serves low-res thumbnails by default). Then run: `bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"`
+ - **Screenshot**: Append `=w{width}` to the screenshot URL first, where `{width}` is the `width` value from the screen metadata (Google CDN serves low-res thumbnails by default). Then run: `bash scripts/fetch-stitch.sh "[screenshot.downloadUrl]=w{width}" ".stitch/designs/{page}.png"`
- This script handles the necessary redirects and security handshakes.
-5. **Visual audit**: Review the downloaded screenshot (`.stitch/designs/{page}.png`) to confirm design intent and layout details.
+5. **Visual audit**: Review the downloaded screenshot (`.stitch/designs/{page}.png`) to confirm design intent and layout details. **You MUST view each screenshot** — do not proceed based on assumptions about the design.
+6. **Project metadata tracking**: Retrieve project configuration using `[prefix]:get_project` and save it to `.stitch/metadata.json` (inside the app folder, and mirrored in the workspace root). Ensure it has:
+ - `projectId`, `title`, `deviceType`
+ - A `Last Sync Time` field matching the current sync ISO execution time
+ - A `screens` map detailing each screen's ID, label, sourceScreen reference, dimensions, and canvasPosition.
+
+### Anti-patterns for Phase 1
+- ❌ Reading `.stitch/designs/*.html` directly without calling MCP `get_screen` first.
+- ❌ Skipping the `fetch-stitch.sh` download script.
+- ❌ Not asking the user when existing files are found.
+- ❌ Skipping the visual audit of `.png` screenshots.
+- ❌ Failing to generate or update `.stitch/metadata.json` and its `Last Sync Time` field upon syncing.
+
+## Phase 2: Style extraction
+
+> **GATE: Phase 2 is complete ONLY when `resources/style-guide.json` has been updated with tokens extracted from the current project's HTML `