google-labs-code/stitch-sdk / .agents/skills/stitch-sdk-pipeline
stitch-sdk-pipeline
VerifiedRun the full Stitch SDK generation pipeline. Use when a new tool is added, or the SDK needs to be regenerated end-to-end.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.7 KB |
SKILL.md
View on GitHub---
name: stitch-sdk-pipeline
description: Run the full Stitch SDK generation pipeline. Use when a new tool is added, or the SDK needs to be regenerated end-to-end.
---
# Stitch SDK Pipeline
This skill orchestrates the full SDK generation pipeline β from capturing MCP tool schemas to publishing a tested, validated package. Use this when:
- The Stitch MCP server adds or changes tools
- You need to regenerate the SDK from scratch
- You want to verify the pipeline is healthy
> [!IMPORTANT]
> **Stage 2 is the only step requiring agent intelligence.** All other stages are deterministic scripts. For Stage 2, use the `stitch-sdk-domain-design` skill.
---
## Prerequisites
- `STITCH_API_KEY` environment variable set
- `bun` installed
- Working directory: project root (`stitch-sdk/`)
---
## Pipeline Stages
### Stage 1: Capture Tool Schemas π€
```bash
// turbo
npm run capture
```
Connects to the Stitch MCP server, calls `tools/list`, and writes the raw schemas to `packages/sdk/generated/tools-manifest.json`. Updates the manifest section of `stitch-sdk.lock`.
**Output**: `packages/sdk/generated/tools-manifest.json` (includes `inputSchema` + `outputSchema` for every tool)
**When to skip**: If `tools-manifest.json` is already up to date and no server-side changes occurred.
---
### Stage 2: Domain Design π§ (Agent)
**Use the `stitch-sdk-domain-design` skill for this stage.**
Read `tools-manifest.json` and edit `packages/sdk/generated/domain-map.json` to map tools β classes β methods.
Key decisions at this stage:
- Which class owns each tool?
- What are the arg routing rules (self, param, computed, selfArray)?
- What is the response projection path?
- Should the method cache data from the construction response?
**Input**: `tools-manifest.json` + `scripts/ir-schema.ts` (the canonical IR contract)
**Output**: `packages/sdk/generated/domain-map.json`
**When to skip**: If `domain-map.json` already has the correct bindings and you only changed `ir-schema.ts` or `generate-sdk.ts`.
---
### Stage 3: Generate TypeScript π€
```bash
// turbo
npm run generate
```
Validates the IR (Zod schema) and every projection (against `outputSchema`), then emits TypeScript files via ts-morph into `packages/sdk/generated/src/`.
**Output**: `packages/sdk/generated/src/*.ts` + updated `stitch-sdk.lock`
If this fails with a projection error, go back to Stage 2 and fix `domain-map.json`.
---
### Stage 4: Build π€
```bash
// turbo
npm run build
```
TypeScript compilation: `packages/sdk/` β `packages/sdk/dist/`.
---
### Stage 5: Unit Tests π€
```bash
// turbo
npm run test
```
Runs core unit tests (vitest) β mocked `callTool`, verifying generated method signatures, caching, and error handling.
---
### Stage 6: Script Tests π€
```bash
// turbo
npm run test:scripts
```
Runs contract tests (IR schema acceptance/rejection) and logic tests (expression builders) using `bun:test`.
---
### Stage 7: E2E Tests π€
```bash
npm run test:e2e
```
Live API tests against the built package. Requires `STITCH_API_KEY` (and `GEMINI_API_KEY` for AI SDK tests). Two test suites:
- **`live.test.ts`** β Direct SDK calls: create projects, generate screens, verify responses.
- **`ai-sdk-e2e.test.ts`** β AI SDK integration via `stitchTools()`: Gemini autonomously calls Stitch tools, generates designs, extracts HTML + Tailwind config, produces modular React components, validates via SWC, and scaffolds a Vite preview app at `.stitch/preview/`.
---
### Stage 8: Lock Validation π€
```bash
// turbo
npm run validate:generated
```
Verifies that `stitch-sdk.lock` hashes match the actual generated files. Catches drift (someone edited generated files manually or forgot to regenerate).
> [!IMPORTANT]
> Always run **after** Stage 3 (Generate). If you run Capture (Stage 1) then Validate without re-generating, the hashes will mismatch because the manifest hash changed.
---
### Stage 9: Skill Audit π§ (Agent)
After the pipeline passes, audit agent skills for freshness. Read the current source of truth and update any skills that reference stale methods, args, or examples.
**Inputs**:
- `packages/sdk/src/index.ts` (public surface)
- Generated class files in `packages/sdk/generated/src/`
- `packages/sdk/src/spec/errors.ts` (error codes)
- `packages/sdk/src/spec/client.ts` (config schema)
**Skills to audit** (in priority order):
1. `stitch-sdk-usage` β highest churn, references specific methods and constructor signatures
2. `stitch-sdk-readme` β must document `stitchTools()`, `toolDefinitions`, and AI SDK integration examples
3. `stitch-sdk-development` β check cache examples match current domain-map patterns
4. `stitch-sdk-domain-design` β check code examples in the cache section
**Skills to skip**: `stitch-sdk-pipeline` (self-referential), `red-green-yellow` (generic methodology).
**What to check**:
- Every method name in a code example exists on its class
- Every import in an example matches an export in `index.ts`
- Constructor signatures match the actual constructors
- Config fields match `StitchConfigSchema`
- Error codes match `StitchErrorCode`
**When to skip**: If only infrastructure code changed (`packages/sdk/src/client.ts`, `packages/sdk/src/proxy/`) and no public API surface changed.
---
## Quick Reference
### Full pipeline (script stages only)
```bash
npm run pipeline
```
Runs Stage 1 β 3 β 4 β 5 in sequence. Does **not** include Stage 2 (agent), Stage 7 (e2e), or Stage 9 (skill audit).
### Starting from a specific stage
| Scenario | Start from |
| ---------------------------------------------------- | ---------- |
| New tool added to MCP server | Stage 1 |
| Need to change how a tool maps to a method | Stage 2 |
| Changed `ir-schema.ts` or `generate-sdk.ts` | Stage 3 |
| Changed code in `packages/sdk/src/` (client, errors) | Stage 4 |
| Just want to verify everything works | Stage 5 |
| Changed AI SDK tools adapter or tool definitions | Stage 5 |
| Public API surface changed | Stage 9 |
### Key files
| File | Location | Role |
| ------------------------ | ----------------------------- | -------------------------------------------------------------------------- |
| `tools-manifest.json` | `packages/sdk/generated/` | Raw MCP tool schemas (Stage 1 output) |
| `domain-map.json` | `packages/sdk/generated/` | IR: tool β class β method mappings (Stage 2 output) |
| `tool-definitions.ts` | `packages/sdk/generated/src/` | Generated JSON Schema tool definitions for AI SDK |
| `tools-adapter.ts` | `packages/sdk/src/` | `stitchTools()` β AI SDK v6 adapter (imported via `@google/stitch-sdk/ai`) |
| `ir-schema.ts` | `scripts/` | Zod schema defining valid IR structure |
| `tool-schema.ts` | `scripts/` | TypeScript types for JSON Schema |
| `generate-sdk.ts` | `scripts/` | ts-morph codegen (Stage 3) |
| `stitch-sdk.lock` | `packages/sdk/generated/` | Integrity hashes for drift detection |
| `stitch-html.ts` | `packages/sdk/test/helpers/` | Stitch HTML parser (Tailwind config + font extraction) |
| `component-validator.ts` | `packages/sdk/test/helpers/` | SWC AST validator for generated React components |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path β even casually (like "the xlsx in my downloads") β and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |