When to Use

Zero-knowledge onboarding orchestrator. Walks new users through the conceptual ladder and nudges them to build their first real Section + Template.

Use as the VERY FIRST skill when a user says “I’m new to Studio”, “what is Studio?”, “I want to add Studio to my site”, “how do I start with Studio”, “show me Studio from scratch”. Also defensively when build-section / build-connected-template is invoked by someone unfamiliar with Sections. Do NOT use as reference for someone who’s shipped a Section.

Auth preflight: settle the credential before the first API call. Resolve it OAuth-first per authenticate-cma: CS_OAUTH_ACCESS_TOKEN, else the Contentstack MCP’s stored session. Never ask the user for a session authtoken. If nothing resolves, or a refresh fails with 400 invalid_refresh_token, hand them ! CONTENTSTACK_REGION=<code> npx @contentstack/mcp --auth (it needs a TTY and a browser, so it cannot be run for them) and wait. 403 error_code 316 is a valid credential aimed at another org: fix the org or the api_key, do not re-authenticate.

Start Here: Studio From Zero

Why This Skill Exists

Studio’s value depends on a mental model the user must internalise BEFORE they start building. Skip it and they’ll:

Drop atomic components straight onto routes (one-off pages, no reuse)
Hand-wire bindings per page (slow. Defeats the point)
Build “Sections” as new React components in their repo (misunderstanding: Sections are composition data, not new code)
Skip linked schemas (forfeits auto-binding. Back to manual wiring)
Build N templates as N separate page routes (forfeits the catch-all + URL pattern reuse)

This skill is the on-ramp. It walks five concepts in 10 to 15 minutes, then routes to the right first action.

Task

Step 1: Frame the problem (no jargon yet)

Tell the user verbatim:

Before any code, here’s the problem Studio solves and the new vocabulary you’ll need.

Today’s problem. Every new page on your site is engineering work. A new blog post, a new product, a campaign landing: each one is a route file + a component arrangement + data wiring. Marketing waits on engineering. Engineering rewrites the same hero-grid-CTA pattern for every layout. Adding a page = a deploy.

Studio’s premise. Engineers register your atomic React components ONCE. Authors then compose Sections (reusable parts of a page like a hero or a CTA strip, bound to CMS data once) and arrange those Sections into Templates (whole-page recipes). New pages = new entries in your CMS, not new code.

The whole game is bind once, reuse everywhere. Sections and Templates are how Studio expresses that.

Step 2: Walk the concept ladder (run each in order)

These seven concept skills explain the whole mental model, ~12 minutes total. Run in order. Each builds on the last:

understand-sections: what a Section is. The “part of a page” unit.
understand-linked-schemas: how a Section declares the data shape it needs.
understand-auto-binding: what happens when a Section drops on a Template. Why dropping “just works.”
understand-section-slots: how to make ONE Section serve multiple Templates by leaving swap points open.
understand-templates: what a Template is and how Sections compose into one. Key mental-model rung: Templates compose Sections. A Template is a page-level container. Sections are the units that fill it. Build Sections first, then assemble them into a Template. Templates never model fields directly.
understand-canvas-vs-component: the two SDK mounts split by what they render: <StudioCanvas /> is Section-only (one /canvas route, used inside Studio’s iframe for Section building / authoring / previewing, Templates never render through it). <StudioComponent /> renders Templates, on your real visitor routes AND inside Studio’s template-preview iframe (Studio iframes the env Base URL + Template URL, which is the same route a visitor hits). Sections never render standalone. They only appear inside a Template.
understand-canvas-url: the Canvas URL field that comes up during setup (it points Studio at the <StudioCanvas /> route used for Sections).

After these the user can answer in plain language: “A Section is a reusable part of a page with its CMS binding declared. A Template is a stack of Sections. When I drop a Section on a Template, Studio matches its linked schema to the Template’s content type and auto-binds every prop. Section Slots let one Section serve many Templates with a child-component swap point. Sections author through <StudioCanvas /> at the /canvas route inside Studio’s iframe. Templates render through <StudioComponent /> on my real routes: visitors hit those routes directly, and Studio iframes the same routes when previewing a Template.”

Step 3: Branch by project shape

Ask: ”Are you adding Studio to an existing website, or starting a brand-new one?” Branch:

Path A: Existing website (most common)

The user already has a React app (Next/Vite/CRA/Remix), a Contentstack, and live content. Adding Studio is incremental, and the first phase changes none of their pages.

Phase 1, minimal conversion. convert-project-to-studio drives steps 1 to 6 with the answers pre-filled, so run it rather than the steps by hand:

analyze-project-fit: read-only diagnostic. Confirms a single React (18 or 19), detects framework and locales, picks the install branch.
enable-visual-experience: turn on Live Preview at the stack level (UI-only step).
install-studio: adds the three SDKs and wires the canonical init. Minimal-add branch if Contentstack is already wired.
(Optional) setup-local-https-canvas: only if you need HTTPS-on-localhost for service workers / secure cookies / strict policy. Plain http://localhost:<port> works for the basic Studio iframe.
setup-section-preview: adds the /canvas route mounting <StudioCanvas />, sets Canvas URL.
setup-template-preview-routes: adds the catch-all that mounts <StudioComponent /> behind the existing routes. Code routes win, the app’s own 404 stays, every locale gets a Base URL.

Studio is live at this point. Nothing the user had before renders differently, and authors can build a first Studio page at any URL no code route claims.

Phase 2, once Studio is live:

register-component: register the user’s first 3 to 5 atomic components (the ones they’ll use in the first Section).
build-section (author the first Section. Stop here and celebrate) the first Section authored against real components is the moment Studio “clicks.”
build-connected-template: author the first Template against an existing content type, drop the Section on it.
verify-setup: run the layered smoke test.

After step 8 the user has proof the loop works (register, then Section, then render in canvas). After step 9 they have a live URL rendering a Template against their existing CMS data.

Path B: Brand-new website (greenfield)

The user is starting from scratch. They still need React + a CMS first.

Sequence:

Scaffold a React app (Vite recommended, npm create vite@latest -- --template react-ts. It defaults to React 19, which the SDK supports alongside React 18. No pin needed).
Set up a Contentstack with at least one content type that has fields you’ll bind a Section to (e.g. blog_post with title, subtitle, cover, body).
Then run the same chain as Path A from analyze-project-fit onwards.

For Path B specifically: build 2 to 3 atomic components first (Hero, FeatureCard, CTA) so there’s something to register in step 6. A register-component skill on a half-built component is wasted effort.

Step 4: Set expectations

Tell the user verbatim:

Two things you’ll feel in the first hour:

The first Section feels like overhead. You register a component, declare a linked schema, then drop it once. Why didn’t I just import the component on a page? Because the second time you use it on a different Template, you’ll feel the payoff: zero re-wiring. By the fifth use it’s a 10× return.

You’ll be tempted to skip Sections and bind components directly on Templates. Don’t. Template-level direct binding works for the Template you just authored, but the binding doesn’t travel: when you make a similar Template tomorrow, you’ll wire it again. Sections + linked schemas are what make today’s binding usable tomorrow.

If a part of a page appears on more than one Template, make it a Section. If you’re not sure: make it a Section anyway. Downside is small.

Step 5: Hand off to the first procedural skill

Print the user’s tailored plan as a numbered list (from Step 3’s appropriate path), and offer to invoke the first skill (analyze-project-fit). Wait for explicit user confirmation before any state-changing skill runs.

Inputs Needed From the User

projectShape: existing or new. Determines the branch in Step 3.

Acceptance

This skill succeeds only when ALL of the following are true.

The frame in Step 1 was printed (the user got the “problem and premise” narrative before any jargon).
The user was guided through (or directly read) all six concept skills in Step 2, order matters: Sections, linked schemas, auto-binding, slots, Templates, then Canvas URL.
The user confirmed their projectShape.
The user received their branched, numbered plan (Path A or Path B).
Step 4’s expectation-setting was printed verbatim, both warnings (first-Section-feels-like-overhead, don’t-skip-Sections).
The user was nudged toward Sections + Templates rather than left to invent their own pattern.
The user explicitly confirmed before any state-changing skill was invoked.

Common Pitfalls

Pitfall	Why it bites	Fix
Skipping the concept ladder and going straight to install-studio	User ends up wiring page-by-page, never realizes Sections exist, ships a one-off integration that doesn’t compound	Always run Step 2 first, even if the user is impatient. The 10-minute investment prevents weeks of rework.
Letting the user write Section-shaped React components in their repo	Sections are composition data, not new components. New React code “to be a Section” is wasted work.	Run understand-sections, make sure they see “a Section is composed from atomic components you already have.”
Treating Path B (greenfield) as “easier”	It isn’t: greenfield users still need a CMS stack with real content types and entries before Studio is meaningful. Empty stack = nothing to bind.	Step 3 Path B explicitly sequences CMS setup before Studio install.
Recommending build-section before register-component	A Section can’t exist without registered atomic components to compose.	Path A step 6 (register-component) comes BEFORE step 7 (build-section).
Pushing the user toward complex setups (Section Slots, exposed props) on day one	These are advanced: premature complexity confuses new users	Keep the first chain to: register components, one Section, then one Connected Template. Section Slots and exposed props are post-success additions.