google-labs-code/stitch-sdk / .agents/skills/stitch-sdk-domain-design
stitch-sdk-domain-design
VerifiedDesign the domain model for the Stitch SDK. Use when mapping MCP tools to domain classes and bindings in domain-map.json. This is Stage 2 of the generation pipeline.
Stitch SDK Domain Design
This skill teaches you how to perform Stage 2 of the generation pipeline: reading tool schemas and producing domain-map.json — the intermediate representation that drives codegen.
Your Inputs
tools-manifest.json— raw MCP tool schemas captured from the server (includesoutputSchema)ir-schema.ts— Zod schema defining valid domain-map structure (the canonical contract)- Existing
domain-map.json— the current IR (if extending, not starting fresh) - The
stitch-sdk-developmentskill — for understanding the pipeline context
Your Output
A valid domain-map.json with two sections: classes and bindings, validated by ir-schema.ts.
[!IMPORTANT] Your output is validated twice by the codegen: structurally (Zod IR schema) and semantically (projection steps verified against
outputSchemafrom the tools-manifest).
Designing Classes
Each class represents a domain entity. Ask: "What noun does the user interact with?"
{
"Stitch": {
"description": "Main entry point. Manages projects.",
"constructorParams": [],
"isRoot": true,
"factories": [
{
"method": "project",
"returns": "Project",
"description": "Create a Project handle from an ID."
}
]
}
}
Key decisions:
| Field | Purpose | Example |
|---|---|---|
constructorParams | Fields stored on the instance | ["projectId", "screenId"] |
reference | Identity-map keys (.id aliases the LAST key) | { "keys": ["projectId", "screenId"] } |
parentField | Which param is injected from a parent class | "projectId" |
factories | Local factory methods (no API call) | [{ "method": "project", "returns": "Project" }] |
sideEffects | Handwritten extension methods (declared, never generated) | [{ "method": "upload", "reason": "private_rest", "specPath": "src/spec/upload.ts" }] |
extensionPath | Module re-exporting the class with handwritten methods | "../../src/project-ext.js" |
[!IMPORTANT] The IR schema is STRICT. Unknown keys are hard validation errors, not silently ignored. Per-field source-mapping helpers described in older docs were never implemented and do not exist — identity fields are populated by the EntityManager from
reference.keys, resourcenameparsing, andidfallback. If validation rejects a key you expected to exist, the feature does not exist — do not work around it.
Designing Bindings
Each binding maps one MCP tool to one class method. Ask: "Who owns this action?"
Arg routing
| Type | Meaning | Code generated |
|---|---|---|
self | From this.field | projectId: this.projectId |
param | From method parameter | prompt: prompt |
computed | template interpolation ("template": "projects/{projectId}") | name: \projects/${this.projectId}/screens/${screenId}`` |
selfArray | Wrap self field as array | selectedScreenIds: [this.screenId] |
Optional params use "optional": true. Renamed params use "rename": "newName".
A "default": "VALUE" (requires optional: true) is sent when the caller
omits the value: deviceType: options?.deviceType ?? "DESKTOP".
[!IMPORTANT] Method signature shape (D12): required params are positional, in IR order; ALL optional params are emitted into a single trailing
options?: { ... }object.generate(prompt, options?), nevergenerate(prompt, deviceType?).
Response Projections
The returns.projection array tells codegen how to navigate the API response. Each step is a ProjectionStep:
{ prop: string; index?: number; each?: boolean; find?: string; acknowledgeSingle?: boolean }
| Projection | Generated code | Use when |
|---|---|---|
[] (empty) | raw | Direct return (whole response) |
[{ "prop": "projects" }] | raw.projects | Array inside object |
[{ "prop": "outputComponents", "index": 0 }, { "prop": "design" }, { "prop": "screens", "index": 0 }] | raw.outputComponents[0].design.screens[0] | Deeply nested single item |
[{ "prop": "outputComponents", "each": true }, { "prop": "design" }, { "prop": "screens", "each": true }] | flatMap chain | Collect all items across arrays |
[{ "prop": "screenshot" }, { "prop": "downloadUrl" }] | raw.screenshot.downloadUrl | Navigate nested properties |
Decision: Use "index": 0 when extracting a single item. Use "each": true when collecting all items (array result). You cannot use both on the same step. "find": "a.b" scans an array for the first element whose nested path is non-null.
[!TIP] Every
propin a projection is validated against the tool'soutputSchemaat codegen time. If you typo a property name, codegen will fail with a diagnostic listing the available properties. Stepping THROUGH an array withoutindex/each/findis also a codegen error — the emitted chain would beundefinedat runtime.
[!WARNING] Truncation lint: using
indexorfindon an UNBOUNDED array emits a warning — every other element is silently dropped (this exact pattern causedproject.generate()to return one screen of many). Prefer"each": true+"array": true. Only if the result is semantically singular, acknowledge it with"acknowledgeSingle": trueon the step.
Return class wrapping
When returns.class is set, the extracted data is wrapped in a domain class constructor:
{
"returns": {
"class": "Screen",
"projection": [{ "prop": "screens" }],
"array": true
}
}
The codegen automatically spreads parentField into the data if the child class declares one.
Cache-aware methods
Add a cache field with a structured projection to check this.data before calling the API:
{
"cache": {
"projection": [{ "prop": "htmlCode" }, { "prop": "downloadUrl" }],
"description": "Use cached HTML download URL from generation response if available"
}
}
When the cached property is a nested object (like File with a downloadUrl), use multiple projection steps to drill into it.
Generated code:
if (this.data?.htmlCode?.downloadUrl) return this.data?.htmlCode?.downloadUrl;
// ... else call API
Decision Framework
When mapping a new tool, answer these questions:
-
Which class? Look at which fields the tool requires. If it needs
projectIdfromself, it belongs onProjectorScreen. If it needs nothing from self, it belongs onStitch. -
Which method name? Use the verb from the tool name, simplified.
generate_screen_from_text→generate.edit_screens→edit. -
Arguments from self or param? If the caller already has the data (because they're calling a method on themselves), use
self. If they need to provide it, useparam. -
How deep is the return? Check the tool's
outputSchemaintools-manifest.json. Build theprojectionarray step-by-step to navigate to the useful data. -
Should it cache? If the data is available from a previous response (like generation), add a cache field with the projection path.
Validation
After editing domain-map.json:
bun scripts/generate-sdk.ts # Validates IR + projections, then generates
npx tsc --noEmit # Type check
npx vitest run # Unit tests
bun scripts/e2e-test.ts # E2E tests
bun scripts/validate-generated.ts # Lock integrity
If a projection is invalid, you'll see:
❌ Binding "Project.generate" projection step 2:
property "screenz" not found in outputSchema.
Available properties: screens, components, metadata
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: 319k | 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: 196k | 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: 118k | 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 |