When to Use

Read-only diagnostic that inspects the user’s project (package.json, framework, React version, Contentstack deps) and emits a tailored install path before any state-changing skill runs.

Use as the FIRST step when the user wants to add Studio to an existing project, or is unsure if their setup is compatible. Phrases: “add Studio to my app”, “is my project compatible”, “before I install”. Always run before install-studio, install-live-preview, or setup-section-preview. Skip if already run this session.

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.

Analyze Project Fit: Pre-Flight Diagnostic for Studio Install

Why This Skill Exists

install-studio assumes a known project shape. In reality projects vary across:

• React version: the SDK supports React 18 and React 19. @contentstack/studio-react 1.8.0 and later peer-dep react ^18.0.0 || ^19.0.0. The one real blocker is a stale SDK pin: a lockfile already holding @contentstack/studio-react below 1.8.0 on a React 19 app fails with ERESOLVE. Fix the pin, never downgrade React.
• Framework: Next.js needs NEXT_PUBLIC_* env prefixes and SSR-safe init, Vite needs dedupe and a prod-build canvas, CRA needs REACT_APP_*.
• Bundler quirks: Next 16 + Turbopack has tree-shake edge cases. Custom webpack configs may not externalize React.
• Existing Contentstack SDKs: adding Studio to an app that already has @contentstack/delivery-sdk is a minimal-add, not a greenfield install.
• Local serving: Studio iframes the canvas. http://localhost is mixed-content blocked, a self-signed HTTPS cert is untrusted, mkcert must be installed.

Running blind through install-studio against these variants is what produces the long debug sessions documented in STUDIO_INTEGRATION_ISSUES.md (dev-optimizer dual React, stale SDK pin, missing trusted HTTPS, etc.). This skill front-loads the inspection so the next skill receives a clean, known shape.

This skill is read-only. It never writes files, never installs packages, never modifies the project. It produces a plan, the user confirms, then the appropriate downstream skill runs.

Task

1. Inspect the project (no writes)

Run these checks in order:

# 1a. package.json — root + workspace packages if monorepo
cat {{projectRoot}}/package.json

# 1b. Lockfile → package manager
ls {{projectRoot}}/pnpm-lock.yaml {{projectRoot}}/yarn.lock {{projectRoot}}/package-lock.json {{projectRoot}}/bun.lockb 2>/dev/null

# 1c. Workspace / monorepo signals
ls {{projectRoot}}/turbo.json {{projectRoot}}/pnpm-workspace.yaml {{projectRoot}}/nx.json {{projectRoot}}/lerna.json 2>/dev/null

# 1d. TypeScript presence
ls {{projectRoot}}/tsconfig.json 2>/dev/null

# 1e. Single React check (the dual-React problem)
cd {{projectRoot}} && npm ls react 2>&1 | head -20

# 1f. Bundler configs
ls {{projectRoot}}/vite.config.* {{projectRoot}}/next.config.* {{projectRoot}}/webpack.config.* {{projectRoot}}/tsup.config.* 2>/dev/null

# 1g. Local HTTPS readiness
which mkcert ; ls {{projectRoot}}/certs/*.pem 2>/dev/null

# 1h. Deploy target
ls {{projectRoot}}/.vercel/ {{projectRoot}}/netlify.toml {{projectRoot}}/vercel.json {{projectRoot}}/wrangler.toml 2>/dev/null

# 1i. App-side i18n (every locale needs its own env Base URL later)
grep -E '"(next-intl|next-i18next|i18next|react-i18next|react-intl|@lingui/[a-z]+|next-international)"' {{projectRoot}}/package.json
find {{projectRoot}}/app {{projectRoot}}/src/app -maxdepth 2 -type d \( -name '[[]locale[]]' -o -name '[[]lang[]]' \) 2>/dev/null
grep -n "i18n" {{projectRoot}}/next.config.* 2>/dev/null ; ls {{projectRoot}}/middleware.* {{projectRoot}}/src/middleware.* 2>/dev/null

2. Classify the project

From the output above, extract:

2b. Determine the data center: prod region vs non-prod (<env>, stag, …)

Nothing else in the skill pack figures this out, and several skills assume you already have. Establish it here, once, and carry it forward.

Why it matters more than it looks. The Delivery SDK defaults to the US prod CDA, and the Studio React SDK derives its Studio API host from whatever stack you hand it. So a project targeting <env> that never sets host: will silently read and write prod, no error, no warning, wrong data center. Non-prod also has no region shortcut: every host must be overridden explicitly (install-studio § Regional host map).

Resolve in this order, stopping at the first hit:

# 1. Explicit host already in the app?
grep -rnE "https?://|host:|CONTENTSTACK_[A-Z_]+|CMA_HOST|STUDIO_API_HOST|CDA_HOST|PREVIEW_HOST|region" .env* src/ app/ lib/ 2>/dev/null | head

# 2. Region shortcut in use? (prod only — NA/EU/AU/AZURE_NA/AZURE_EU/GCP_NA/GCP_EU)
grep -rn "region:\s*['\"]" src/ app/ lib/ 2>/dev/null | head

3. Ask, if neither is conclusive: and ask for the URL, not the name, because the URL is unambiguous:

   Which Contentstack environment is this stack on? Paste the URL you use to open Contentstack: app.contentstack.com (US prod), a regional prod host, or something like <env>-app.<non-prod-domain> (non-prod).

The editor URL determines every other host. For a non-prod env <env>, the full set is <env>-cdn / -rest-preview / -api / -composable-studio-api / -images .<non-prod-domain>, table in install-studio § Non-prod hosts.

Record it in the report (step 4) as an explicit line. Downstream skills consume it:

3. Choose a path

Pick exactly one based on the classification:

4. Report: what to tell the user

Print a single readable summary block:

✓ Project shape detected:
    Framework:        <Next | Vite | CRA | Remix | Astro | Custom>
    React:            <18.x | 19.x> — <single | duplicate>
    Package manager:  <pnpm | yarn | npm | bun>
    TypeScript:       <yes | no>
    Monorepo:         <yes (turbo/pnpm-workspace/etc.) | no>
    Existing CS SDKs: <none | delivery-sdk | live-preview-utils | studio-react>
    Local HTTPS:      <mkcert ready | not installed>
    Deploy target:    <vercel | netlify | custom | none>
    i18n:             <none | next-intl (always) en,fr | [locale] segment en,de | …>

Chosen path: <A | B | C | D | E | F | G> — <short label>

Next steps (in order):
  1. <exact command if any prep needed, e.g. pnpm add @contentstack/studio-react@latest ...>
  2. Invoke skill: <install-studio | install-studio (minimal-add branch) | …>
  3. Then: <setup-section-preview | setup-local-https-canvas | …>

Blockers to resolve before install:
  • <list, or "none">

Wait for explicit user confirmation before invoking the next skill.

5. Hand-off

Once the user confirms, invoke the next skill in the chosen path. Pass forward what you discovered (framework, package manager, React version, TS) so the downstream skill doesn’t re-prompt for things you already know.

Inputs Needed From the User

1. projectRoot: path to the project. Usually . (current dir).

Acceptance

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

• Inspection commands ran and outputs were classified (no guessing: every signal in the classification table either matched a detection rule or was reported as “not detected”).
• The data center is established and stated explicitly: a prod region (NA/EU/AU/AZURE_NA/AZURE_EU/GCP_NA/GCP_EU) or a non-prod <env> prefix. Never left as “assumed prod”: the SDK silently defaults to US prod, so a wrong assumption writes real data to the wrong data center with no error.
• Exactly one path (A to G, plus H if non-prod) was chosen with justification.
• The summary block was printed including the chosen path + next steps.
• If the path is a blocker (B/C/G), install-studio was NOT invoked: the user is given the prep step and asked to re-run analyze-project-fit after.
• If the path is an enabler (A/D/E/F), the downstream skill was invoked with the discovered context.
• No files were modified by this skill itself.

Common Pitfalls

See Also

• install-studio: the downstream skill for paths A/D/E/F
• setup-section-preview: for the canvas-iframe wiring (paired with setup-local-https-canvas)
• setup-local-https-canvas: mkcert recipe for trusted local HTTPS
• troubleshoot-canvas: reactive diagnosis if install proceeded and something failed downstream
• verify-setup: layered smoke test after install