// Generate or update the README for the Stitch SDK. Use the Bookstore Test structure and source the current API from the codebase. Use when the README needs to be written or updated.
| name | stitch-sdk-readme |
| description | Generate or update the README for the Stitch SDK. Use the Bookstore Test structure and source the current API from the codebase. Use when the README needs to be written or updated. |
This skill produces the README for @google/stitch-sdk. It combines a structural strategy (the Bookstore Test) with instructions for sourcing the current API from the codebase — so the README stays accurate as the SDK evolves.
Do not hard-code the API surface. Read it from the codebase at invocation time:
| What you need | Where to find it |
|---|---|
| Public exports (full surface) | packages/sdk/src/index.ts |
| Domain class methods + signatures | Source files for each exported class (sdk.ts, project.ts, screen.ts) |
| Generated method bindings | packages/sdk/generated/domain-map.json → bindings[] array |
| Handwritten methods | Methods in class source files that aren't in domain-map bindings (e.g. Screen.edit, Screen.variants) |
| AI SDK tools adapter | packages/sdk/src/ai.ts → subpath entry for stitchTools() |
| Generated tool definitions | packages/sdk/generated/src/tool-definitions.ts → JSON Schema for each tool |
| Tool client methods | packages/sdk/src/client.ts |
| Error codes | packages/sdk/src/spec/errors.ts → StitchErrorCode |
| Config options | packages/sdk/src/spec/client.ts → StitchConfigSchema |
| Proxy config | packages/sdk/src/proxy/core.ts |
After reading these files, you have the complete API surface. Structure it using the Bookstore Test template below.
A reader decides whether to use a library the same way a person decides to buy a book: they glance at the cover, read the inner flap, then commit to reading the book. The README must earn the reader's attention at each stage.
A single sentence stating what problem this library solves — not what the library is. The reader should recognize their own situation. No taglines, no badges, no logos.
For this SDK, the cover is about generating UI from text and extracting HTML/screenshots programmatically.
Good: "Generate UI screens from text prompts and extract their HTML and screenshots programmatically." Bad: "The official TypeScript SDK for Google Stitch, a powerful AI-powered UI generation platform."
Immediately show the library in use. Code first, not setup.
Primary workflow — the punchline everything in the SDK exists to produce:
project(id) → generate → getHtml
Show this as the first code block, with one line noting the env var requirement. Do not show installation, imports, or config before this. Show callTool("create_project", ...) separately for project creation.
Secondary workflows — reveal depth progressively:
stitch.listTools(), stitch.callTool()) — zero setupStitchToolClient (custom API key, base URL)stitchTools() — import from @google/stitch-sdk/ai, show generateText with tools: stitchTools() and stepCountIsRules for this section:
STITCH_API_KEY is enough before the first example.npm install @google/stitch-sdk first (core SDK, standalone). Then show npm install @google/stitch-sdk ai for AI SDK users. The ai package is only needed when importing from @google/stitch-sdk/ai.// ... elisions.The reader is committed. Document the full API as a reference.
Structure by class in this order: Stitch → Project → DesignSystem → Screen → StitchToolClient → toolDefinitions / toolMap → stitchTools() (AI SDK) → StitchProxy → stitch singleton.
Each entry should have:
Setup, authentication, and configuration go here — after the reader has already decided the library is worth using.
Write like a colleague explaining their work to another engineer. Be direct. Be specific. Don't sell — inform. If a feature has limitations, state them. If setup is complex, say so.
After generating the README, verify:
index.ts?index.tsStitchToolClient (agents), stitchTools() (AI SDK)| Anti-pattern | Why it fails |
|---|---|
| Leading with badges, logos, or status shields | Visual noise before the reader knows what the library does |
| "Getting Started" as the first section | Forces setup before demonstrating value |
| Feature bullet lists without code | Tells instead of shows |
| "Easy to use", "simple", "just works" | Self-congratulatory claims that invite skepticism |
| Long install/config blocks before any usage | Asks for investment before demonstrating return |
| Collapsible sections hiding core API docs | Buries the content committed readers came for |
| Hard-coding the API in docs without sourcing | Goes stale when tools are added |
Use the Stitch SDK to generate, edit, and iterate on UI screens from text prompts, manage projects, and retrieve screen HTML/images. Use when the user wants to consume the SDK in their application.
Generates a deeply contextual, progressive-disclosure briefing for any GitHub repository. It builds a mental model of the code before analyzing issues and PRs to provide actionable insights. Use when asked for a "GitHub report," "repo status," "daily briefing," or to "catch up on a codebase."
Develop the Stitch SDK. Covers the generation pipeline, dual modality (agent vs SDK), error handling, and Traffic Light (Red-Green-Yellow) implementation workflow. Use when adding features, fixing bugs, or understanding the architecture.
Find bugs in the Stitch SDK using a real API key. Covers standard functional edges and tricky situations.
Run the full Stitch SDK generation pipeline. Use when a new tool is added, or the SDK needs to be regenerated end-to-end.
Enforces a disciplined Red-Green-Refactor (TDD) workflow in TypeScript/Node.js. Use this whenever creating new features, fixing bugs, or migrating logic to ensure high-quality, verifiable implementations.