@cometchat/cometchat

name	cometchat
description	Entry-point for CometChat integration in any React, React Native, Angular, Android, Flutter, or iOS project — web (React/Next.js/React Router/Astro), React Native (Expo/bare), Angular (12-15), native Android (V6 stable, V5 legacy), Flutter (V6 stable, V5 legacy), and native iOS (V5 stable). Detects the framework, gathers requirements through an interactive conversation, and writes production-quality integration code.
license	MIT

Ground truth: the cometchat detect --json output + the per-platform *-core skills this dispatcher routes to + the packages/registry catalogs. (Official docs linked below.) Verify symbols against the installed package/source before relying on them.

Use this skill when

The user wants to add CometChat to any kind of project. Trigger phrases:

• /cometchat (or invoke the cometchat skill via your agent's mechanism — keyword "cometchat" or "integrate chat" works in most agents)
• "add cometchat", "integrate cometchat", "add chat to my app"
• "add messaging", "add chat ui", "add in-app chat"
• Customize an existing CometChat integration — "make the chat match my brand", "change the chat colors / theme", "style the message bubbles", "translate the chat / add a language", "change the notification (or call) sounds". These route through this dispatcher too: detect the framework, then load the family's *-theming + *-customization (+ cometchat-i18n for localization) skills. If .cometchat/state.json already exists, jump to the Step 7 iteration menu's customization options instead of re-running Phase A.

This is the entry point for every framework. Do NOT invoke framework-specific skills directly — this dispatcher detects the framework first and routes to the right ones.

Supported frameworks:

Family	Frameworks
Web	React (Vite/CRA), Next.js, React Router v6/v7, Astro
React Native	Expo (managed + Expo Router), bare RN CLI
Angular	Angular 17-21 (standalone components; @cometchat/chat-uikit-angular@5)
Android	V6 stable (Compose + Kotlin Views, chatuikit-{compose,kotlin}-android:6.x) / V5 legacy (Java + Kotlin Views, chat-uikit-android:5.x)
Flutter	V6 stable (Bloc-based, cometchat_chat_uikit:^6.0) / V5 legacy (GetX-based, cometchat_chat_uikit:^5.2)
iOS	V5 stable (Swift; SwiftUI + UIKit hosting; CometChatUIKitSwift:~> 5.1)

The web family loads @cometchat/chat-uikit-react + @cometchat/chat-sdk-javascript. The RN family loads @cometchat/chat-uikit-react-native + @cometchat/chat-sdk-react-native. The Angular family loads @cometchat/chat-uikit-angular + @cometchat/chat-sdk-javascript. The Android family loads com.cometchat:chatuikit-{compose,kotlin}-android:6.x (V6 — stable, recommended) or com.cometchat:chat-uikit-android:5.x (V5 — legacy) from Maven Central. The Flutter family loads cometchat_chat_uikit:^6.0 (V6 — stable, recommended; calls fold into the same package) or cometchat_chat_uikit:^5.2 (V5 — legacy; pair with cometchat_calls_uikit:^5.0 for calls) from the Cloudsmith Dart pub-hosted registry. The dispatcher decides which set after Step 1's detection.

How v3 works

v3 skills are interactive and conversational. You don't just detect the framework and dump code. You have a conversation with the developer to understand their project, their use case, and exactly where chat should go — THEN you write code that fits.

Pattern skills (loaded from your context as plain files — not via your agent's skill-loading mechanism):

• cometchat-core (web) / cometchat-native-core (RN) / cometchat-angular-core (Angular) / cometchat-android-{v5,v6}-core (Android) / cometchat-flutter-{v5,v6}-core (Flutter) — init, login, provider chain, env vars, anti-patterns
• cometchat-components (web) / cometchat-native-components (RN) / cometchat-angular-components (Angular) / cometchat-android-v5-components or cometchat-android-v6-{compose,kotlin}-components (Android) / cometchat-flutter-v6-components (V6 only — V5 splits into -conversations/-messages/-users-groups) — component catalog, props, composition
• cometchat-placement (web) / cometchat-native-placement (RN) / cometchat-angular-placement (Angular) / cometchat-android-v5-placement or cometchat-android-v6-{compose,kotlin}-placement (Android) / cometchat-flutter-v6-placement (V6 only) — WHERE to put chat
• One per-framework skill (cometchat-{react,nextjs,react-router,astro}-patterns, cometchat-native-{expo,bare}-patterns, cometchat-angular-patterns, the v5/v6 Android sub-tree, or the Flutter v5/v6 sub-tree) — framework-specific details

Key principle: ask, don't assume. Every piece of information you need from the user should be asked explicitly. Don't guess the route path, don't guess where the trigger button goes, don't guess the auth system.

Steps

Clarification contract (ALL coding agents) — read references/asking-questions.md. Everywhere the steps below say "ask the user", "render an AskUserQuestion", "MUST ask", or "NON-NEGOTIABLE prompt", they mean: follow that contract. AskUserQuestion is only Claude Code's name for it — on Codex / Cursor / Gemini CLI / Windsurf / any agent without that primitive, render the question as a numbered text list and WAIT for a real answer (never default, never infer; auto/approval mode does not authorize skipping). Map the answer by value/label, not ordinal position, accept a free-text fallback, and if running headless, STOP and emit the question rather than guessing. This contract governs every prompt in this skill and all skills it routes to.

Step 1 — Detect framework + map the project

If the CLI itself can't run — degrade, don't dead-end. Every step below calls npx @cometchat/skills-cli …. That can fail to launch (no network to fetch the package, npx/Node absent, a sandbox that blocks process spawn or the npm registry) — distinct from the CLI running and returning a JSON error (handled in the error-handling section near the end). When a command can't launch at all:

• detect → detect by hand. Everything the CLI's detector keys on is in the files this step already tells you to read: package.json deps (@cometchat/chat-uikit-react → web, …-react-native → RN, …-angular → Angular), pubspec.yaml (Flutter), build.gradle (Android), Podfile/Package.swift (iOS), plus the router/version markers. Determine the framework + version from those and continue.
• config show → treat as no saved config; read .cometchat/config.json directly if it exists, else proceed greenfield and ask the questions.
• Action commands (auth login, apply-feature, builder export, verify) genuinely need the CLI. If one can't run, don't silently skip it — tell the user it's unavailable, give the manual dashboard equivalent (e.g. fetch creds from app.cometchat.com → Credentials; toggle the extension in Extensions), and continue best-effort. Never STOP the whole flow just because npx is unavailable — manual detection + reading the project is a complete substitute for routing.

First, check if .cometchat/config.json exists:

npx @cometchat/skills-cli config show --json

If config exists with previous answers, tell the user:

"I see you've set up CometChat before. Using your saved config: Framework: {framework}, App: {appId}, Intent: {intent}. Want to continue with these, or start fresh?"

If no config, run detection:

npx @cometchat/skills-cli detect --json

The JSON output includes framework (one of reactjs, nextjs, react-router, astro, expo, react-native, angular, android, flutter, ios, or null), framework-specific fields (router, expo_mode, react_native_version, android_version, flutter_version, env_prefix), and a compatibility.supported flag. If supported is false, stop and surface the warnings.

If framework === null — greenfield with no project at all (ENG-35718)

A null framework means the working directory has no recognizable scaffold — no package.json, no pubspec.yaml, no AndroidManifest.xml, no Podfile, no Xcode project. The earlier behavior dumped the user into a vague "want me to create one?" with two unlabeled options. Replace it with a named-scaffold prompt so the user picks a target deterministically:

"I don't see a project here yet. Want me to create one? Pick the closest match — you can change details after:

1. React (Vite) — fastest web demo; npm create vite@latest cometchat-demo -- --template react-ts
2. Next.js (App Router) — production-grade web with SSR; npx create-next-app@latest cometchat-demo --typescript --app
3. Expo (managed) — fastest mobile demo; npx create-expo-app@latest cometchat-demo --template
4. Other — tell me what framework you're using and I'll skip the scaffold step.

What sounds right?"

Render this as an AskUserQuestion with the same 4 options. After the user picks, run the scaffold command, cd into the new directory, then re-run detect so the rest of the dispatcher behaves as if framework had been detected normally. Do NOT proceed to Step 2 without a real framework — every step below assumes one exists.

If the user declines all four (chooses "Other" and then says "no, I just wanted to look around"), stop politely and tell them: "You can run /cometchat again from inside a React / Next.js / Expo / Angular / Android / iOS / Flutter project and I'll detect it automatically." Don't try to integrate into an empty directory — every subsequent step will fail.

Android — android_version is load-bearing. When framework === "android", the detect output includes android_version: "v5" | "v6" | null. The cohort selects which V5 or V6 pattern set to load — V6 (stable + recommended, chatuikit-{compose,kotlin}-android:6.x, Compose + Kotlin Views split) and V5 (legacy, chat-uikit-android:5.x, Java + Kotlin Views) are different SDKs with different APIs. Treat them as separate routing targets even though both live under --family android. V6 went GA 2026-05-25 (docs) — was beta in earlier /cometchat releases; the prompt + recommendation flipped from V5 → V6 in v4.3.0.

If android_version is null, the project is greenfield (no cometchat dep yet). Ask the user:

"Which CometChat Android UI Kit do you want to use? V6 is the latest stable SDK (recommended; Compose + Kotlin Views split, went GA 2026-05-25). V5 is the legacy SDK (Java + Kotlin Views — still supported but no new features)."

Save the choice into .cometchat/config.json under androidVersion:

npx @cometchat/skills-cli config save --android-version v5 --json

The CLI accepts --android-version v5 / v6 and --flutter-version v5 / v6 flags (added 2026-05-22 — F46 fix). Subsequent /cometchat runs read this from config and don't re-ask.

Flutter — flutter_version is load-bearing too. When framework === "flutter", the detect output includes flutter_version: "v5" | "v6" | null. V6 (stable + recommended) is Bloc-based (cometchat_chat_uikit:^6.0, calls folded into the same package). V5 (legacy) is GetX-based (cometchat_chat_uikit:^5.2; pair with cometchat_calls_uikit:^5.0 for calls). The two cohorts have different state-management primitives, different barrel exports, and different theme APIs — never mix them. Same --family flutter install ships both sets; routing picks the right one. V6 went GA 2026-05-25 (docs) at version 6.0.1 — was 6.0.0-beta2 in earlier /cometchat releases; the prompt + recommendation flipped from V5 → V6 in v4.3.0.

If flutter_version is null, ask the user:

"Which CometChat Flutter UI Kit do you want to use? V6 is the latest stable SDK (recommended; Bloc-based, calls folded into the same package, went GA 2026-05-25 at 6.0.1). V5 is the legacy SDK (GetX-based — still supported but no new features)."

Save the choice into .cometchat/config.json under flutter_version.

Then read the project yourself — this is critical.

For web frameworks (reactjs, nextjs, react-router, astro):

• package.json — name, dependencies, scripts
• The source directory structure — list all directories under src/ or app/
• Find the router: createBrowserRouter, app/ directory, pages/, react-router.config.ts, astro.config.*
• Find the layout: App.tsx, layout.tsx, root.tsx, Layout.astro
• Find the nav: components with "nav", "header", "sidebar" in name
• Find existing pages/routes: list them so you can reference them later

For React Native (expo, react-native):

• package.json — name, RN version, all dependencies, scripts
• Entry file — index.js or App.{tsx,jsx} or app/_layout.tsx (Expo Router)
• Navigation — look for @react-navigation/native, @react-navigation/stack, @react-navigation/bottom-tabs, or expo-router
• Existing screens — list all files under screens/, src/screens/, app/, or wherever routes live
• Existing nav structure — read the root navigator to see stack vs tab vs drawer layout

For Angular (angular):

• package.json — name, @angular/core version (17-21 supported; the v5 kit's peer range is >=17 <22), all @angular/* deps
• angular.json — workspace config; identify the project name + sourceRoot; the build.options.styles array (where the kit's css-variables.css is registered) + the assets glob
• Bootstrap — standalone: src/main.ts (bootstrapApplication) + src/app/app.config.ts (providers). v5 is standalone-first — there is no NgModule/CUSTOM_ELEMENTS_SCHEMA. (A legacy NgModule app must migrate to standalone, or pin the v4 legacy kit — different skill.)
• Routing — src/app/app.routes.ts (provideRouter / loadComponent); list all routes
• Layout — src/app/app.component.{ts,html}; identify nav, sidebar, header components
• Existing pages/components — list under src/app/pages/, src/app/components/, or wherever the project organizes them
• Environment files — src/environments/environment.ts (and .prod.ts); credentials live here, NOT in .env

For Android (android):

• settings.gradle (or .kts) — module list; usually :app plus optional library modules
• Root build.gradle (or .kts) — top-level plugins, repositories, classpath versions
• App build.gradle (or .kts) — dependencies (this is where the cometchat dep lives), Android plugin, applicationId, minSdk/targetSdk/compileSdk, buildConfigField entries
• AndroidManifest.xml — root <application> class, permissions, <activity> entries, deep links
• Source dirs: app/src/main/java/<pkg>/ (Java) and/or app/src/main/kotlin/<pkg>/ (Kotlin)
• For V6 stack split: presence of androidx.compose.ui:ui or compose.material3 in deps signals Compose; otherwise Kotlin Views (XML layouts under app/src/main/res/layout/). Many V6 projects have both — ask the user which surface chat lands in.
• gradle.properties and local.properties — credentials live here as cometchat.appId=... / cometchat.region=... / cometchat.authKey=..., exposed to code as BuildConfig fields via buildConfigField in the app build.gradle. NOT in .env.
• Application class (e.g. MyApp extends android.app.Application) — init goes in onCreate(). Note the class FQN; you'll wire CometChatUIKit.init(this, settings, callback) here.

For Flutter (flutter):

• pubspec.yaml — package name + Dart SDK constraint + Flutter SDK constraint + dependencies: (this is where cometchat_chat_uikit lives)
• For V5: a typical project has BOTH cometchat_chat_uikit:^5.2 AND cometchat_calls_uikit:^5.0 if calls are needed. V6 folds calls into the single cometchat_chat_uikit:^6.0 package (no separate calls package; depends on cometchat_calls_sdk: >=5.0.2 <6.0.0 transitively).
• lib/ — Dart source. The app entry is lib/main.dart (the void main() => runApp(...) site); init goes in main() or in a top-level Stateful/State.initState().
• lib/<config>.dart (or similar) — credentials. There is NO Flutter .env convention — credentials are typically defined as const Dart values in a config file, OR injected at compile time via --dart-define=COMETCHAT_APP_ID=... flags read inside Dart with String.fromEnvironment. NOT a .env file at runtime.
• android/app/build.gradle and ios/Runner/Info.plist — platform-specific config (FCM service registration, Push capabilities, microphone/camera Info.plist entries for calls). Flutter projects DO have these subdirs but they're configured Flutter-side; do not run the native skill flows.
• For V5 vs V6: V5 uses GetX (get in deps); V6 uses flutter_bloc + equatable. Their controllers, observers, and theming are different — match the integration code to the detected cohort.

For iOS (ios):

• <App>.xcodeproj and/or <App>.xcworkspace — Xcode project / workspace. The .xcworkspace is preferred when CocoaPods is in use (open it, NOT the .xcodeproj).
• Podfile (CocoaPods) — pin pod 'CometChatUIKitSwift', '~> 5.1' and run pod install. Look for platform :ios, '13.0' (or higher) — V5 needs iOS 13+.
• Package.swift (Swift Package Manager) — dependencies: block adds https://github.com/cometchat/cometchat-uikit-ios. Both SPM and CocoaPods are supported; check which the project uses.
• App entry — <App>App.swift (SwiftUI) or AppDelegate.swift + SceneDelegate.swift (UIKit). Init goes in @main struct App.init() (SwiftUI) or application(_:didFinishLaunchingWithOptions:) (UIKit).
• Info.plist — for calls add NSMicrophoneUsageDescription + NSCameraUsageDescription; for push add the APNs entitlement and a BackgroundModes entry with remote-notification (and voip for VoIP push).
• Credentials: NO .env at runtime. Use a Secrets.swift const enum/struct (gitignored) or an *.xcconfig file with COMETCHAT_APP_ID = ... exposed as Build Settings. The skill teaches both.
• Mixed-stack apps (SwiftUI + UIKit): the kit ships UIKit UIViewControllers and exposes them via UIViewControllerRepresentable for SwiftUI hosting. Identify which surface chat lands in (SwiftUI screen vs UIKit nav stack) and follow the matching pattern.

Store this mental map — you'll use it throughout the conversation.

Post-detect order of operations — run these gates IN THIS ORDER

The moment detect --json returns, run the following in order before you write anything or commit to a plan. Each is detailed in its own subsection below; this is the precedence when more than one applies:

1. Pattern skills installed? (see "Pattern skills not installed? — CHECK THIS FIRST") — if the framework's pattern skills aren't loaded, install them and have the user re-run now, before anything else. A late discovery is the worst-timed interruption.
2. version_conflict gate (see "Version-conflict pre-flight") — STOP if the installed UI Kit major doesn't match what the skills target, or both V5+V6 are declared.
3. coexistence gate (see "Coexistence pre-flight") — STOP if a competing chat/calling SDK is present; carry the Firebase/SW advisories into the push journey.
4. Step 1.5 "I see you" summary (below) — only once the gates pass, narrate what you found, then continue to Step 2.

Gates 1–3 are hard stops that can each send the user away to fix something; run them before the Step 1.5 summary so you don't narrate a plan you then have to retract. (The subsections appear below in roughly this order, but this list is the authoritative precedence.)

Then show the user what you found — Step 1.5 (the "I see you" moment)

This is the most important moment of the whole flow. After running detection + reading the project, narrate what you found in 3–5 specific, observation-grounded bullets BEFORE asking any question. The user should feel that you understand their project before deciding whether to trust you with it.

The shape (use it verbatim — the structure earns trust):

Taking a look at your project...

• {Framework} + {Build tool} {version} {with TypeScript / JavaScript / etc., as detected}
• {Router or nav state} — {one observation about how routing is set up, or "no router yet" for greenfield}
• {Auth system status} — {"NextAuth detected → I'll wire token-based login", or "no auth detected → I'll start with dev mode + a test user; you can upgrade later"}
• {Existing CometChat state} — {"existing cometchat/ folder with X — I'll patch around it", or "fresh start — no prior CometChat code"}
• {One personal observation} — {something specific you noticed: "Tailwind classes throughout", "shadcn/ui components", "monorepo with apps/* and packages/*"}

Ready to set this up? I'll walk you through account setup, then ask where chat should live.

The rules for this moment:

1. Be specific, not generic. "Vite + React 19 + TypeScript" beats "a React project." Read the actual versions from package.json.
2. Five bullets max. Beyond five, it stops feeling observational and starts feeling like a recital. Cut to what's interesting about the project.
3. Lead with what's load-bearing. Framework + version, router, auth, existing CometChat, then one personal touch. The personal touch is what makes it land — show you actually looked.
4. Skip the bullet if there's nothing to say. No router on greenfield → say "no router yet"; don't invent one. No auth → say "no auth detected"; don't list every package you didn't find.
5. End with a single confident question. Not five questions. The flow continues into Step 2 (credentials) or Step 3 (placement) — let the next step ask.

Examples of good vs bad bullets:

✓ Good (specific, observational)	✗ Bad (generic, unfounded)
"Vite + React 19 + TypeScript, Tailwind for styling"	"A React project with TypeScript"
"React Router v7 detected (routes.ts + react-router.config.ts)"	"Some routing is configured"
"NextAuth in auth.config.ts — I'll mint CometChat tokens server-side via your existing session cookie"	"Authentication is set up"
"shadcn/ui detected (components/ui/*) — I'll use your existing Button + Dialog primitives in the chat trigger"	"Some UI components are present"
"Monorepo: apps/web is your dashboard, apps/marketing is the public site — I'll integrate into apps/web"	"This is a monorepo"

For greenfield projects (the test case):

Taking a look at your project...

• Vite + React 19 + TypeScript — fresh cometchat-test-app scaffold
• No router yet — for the demo, chat will mount in src/App.tsx directly; we can move it to a route later
• No auth system detected — I'll set you up in dev mode; we'll pick a test user (default cometchat-uid-1 through uid-5) when I confirm credentials in the next step; production auth is a one-flag upgrade later
• Fresh start — no existing CometChat code to patch around

Ready to set this up? I'll get you a CometChat account first, then ask where chat should live.

This moment costs ~5 seconds of conversation but anchors the rest. Skip it and the user feels like they're talking to a script. Run it well and the rest of the flow feels effortless.

---

Compatibility baselines (the CLI enforces these):

• Web: react@<18 → upgrade required; nextjs@<13 → warning; astro@<4 → warning
• RN: react-native@<0.70 → upgrade required; expo@<49 → upgrade required
• Angular: @angular/core@<17 → upgrade required (v5 kit peer range is >=17 <22); skill verified against v21 standalone
• Android V5: minSdk@<21 → upgrade required; minSdk@<24 → warning; AGP@<7.0 → warning
• Android V6: minSdk@<28 → upgrade required (V6 raised the floor from API 23 to API 28); Kotlin@<1.9 → warning; for Compose stack, Compose BOM@<2024.x → warning
• Flutter V5: Dart SDK <2.17 → upgrade required; Flutter <2.5 → warning; Android minSdk 24 (Flutter platform default) when V5 is in use
• Flutter V6: Dart SDK <2.17 → upgrade required; Flutter <2.5 → warning; Android minSdk 26 REQUIRED (cometchat_calls_sdk in V6 raised the floor)
• iOS V5: iOS deployment target <13 → upgrade required; Swift <5.0 → upgrade required; Xcode 15+ requires ENABLE_USER_SCRIPT_SANDBOXING = NO in Build Settings (or the post_install Podfile hook)

Version-conflict pre-flight — STOP if detect reports version_conflict (P0-6)

(Gate 2 in the post-detect order above — runs after the pattern-skills check, before the coexistence gate and the Step 1.5 summary.)

The moment detect --json returns, check version_conflict. If it is non-null, STOP — do NOT write integration code yet. It fires when the project already has a CometChat UI Kit at a major version these skills don't target (e.g. chat-uikit-react v5 in a v6-targeted web project), or when BOTH a V5 and a V6 UI Kit are declared (Android/Flutter half-migrated / duplicate tree). Proceeding emits guidance for the wrong major → duplicate class / unresolved reference / won't-compile failures the user can't easily trace. Surface version_conflict.detail to the user and ask how to reconcile (upgrade the installed kit to the targeted major, or load the matching-version skills, or remove the cohort they're not integrating) before Step 2. Re-run detect after they fix it. This is a gate, not a warning.

Coexistence pre-flight — STOP if detect reports a competing chat SDK (P0-10)

(Gate 3 in the post-detect order above — runs after the version-conflict gate, before the Step 1.5 summary.)

Also check coexistence in the same detect --json output. It surfaces three collisions you must resolve before mounting CometChat:

• coexistence.competing_sdks lists other chat / calling / push providers already in the project (Sendbird, Stream, Twilio, PubNub, TalkJS, Agora, OneSignal). If any entry has kind: "chat" or "calling", STOP — silently adding CometChat means two chat providers mounted in one tree, duplicate WebSocket connections, and a confusing double UI. Ask the user (use the clarification contract — references/asking-questions.md):

  "I see {name} ({coordinate}) already in this project. How do you want to proceed?"

  1. Replace it — I'll integrate CometChat and leave the old SDK's code in place for you to remove (I won't delete it without confirmation).
  2. Run alongside — keep both, namespaced; chat stays on {name}, CometChat powers a new surface. (Heavier; two realtime stacks.)
  3. Switch fully — integrate CometChat now and you'll migrate {name}'s usages over later.

  WAIT for the answer; route accordingly. Never auto-delete the competing SDK's files or deps — that's the user's call.

• coexistence.existing_firebase: true — the project already wires Firebase. CometChat push is FCM-based, so on the -push journey you must reuse the same Firebase app (don't call initializeApp a second time) and merge rather than overwrite firebase-messaging-sw.js. Carry this fact into the push skill; it's an advisory, not a hard stop for chat-only integration.
• coexistence.existing_service_workers — lists existing SW files at paths CometChat web push would write to. Before generating firebase-messaging-sw.js, confirm you won't clobber the app's offline/caching logic; merge the messaging handlers into the existing worker instead.

A competing chat/calling SDK is a gate (ask before proceeding). Firebase + service-worker entries are advisories you must honour on the push journey.

Pattern skills not installed? — CHECK THIS FIRST

(Gate 1 in the post-detect order above — the highest-precedence gate; run it before the version-conflict/coexistence gates and before the Step 1.5 summary, even though it appears last in this section for readability.)

Run this check the moment detect returns a framework — BEFORE the Step 1.5 "I see you" summary, BEFORE credentials (Step 2), BEFORE any AskUserQuestion, and BEFORE creating a Visual Builder. It is a gate, not a contingency. If the framework's pattern skills are missing, install them and tell the user to re-run right now. Do NOT lazily discover the gap later (e.g. when you try to read a pattern skill at code-gen) — agents don't hot-reload skills mid-session (see the re-run note below), so discovering it late forces the user to re-run after they've logged in, picked an app, and customized their Visual Builder. That's the worst-timed possible interruption. Catch it at second 5, not at the finish line.

The dispatcher routes to web pattern skills (cometchat-{core,components,placement,*-patterns}), RN pattern skills (cometchat-native-{core,components,placement,*-patterns}), or Angular pattern skills (cometchat-angular-{core,components,placement,patterns}) based on the detected framework. If the matching set isn't loaded — i.e. the user has only the dispatcher in .claude/skills/, OR they installed only @cometchat/skills (web) but the project is RN/Angular, OR vice versa — install the missing package yourself. Do NOT stop and ask the user to run the npx command manually — that turns a 0-step recovery into a 2-step recovery for no benefit.

To check whether the pattern skills are loaded, attempt to read cometchat-core/SKILL.md (web), cometchat-native-core/SKILL.md (RN), or cometchat-angular-core/SKILL.md (Angular) from your loaded skills context. If the read fails, the package isn't installed — run the installer.

If framework is expo or react-native AND cometchat-native-core is NOT loaded:

npx @cometchat/skills add --family native

If framework is reactjs, nextjs, react-router, or astro AND cometchat-core is NOT loaded:

npx @cometchat/skills add --family web

Important — --family <name> is non-negotiable. Without the family flag, npx @cometchat/skills add (default) installs only the cross-family base skills (cometchat dispatcher + i18n + a11y + calls dispatcher). It does NOT install cometchat-core, cometchat-react-patterns, cometchat-placement, etc. — the framework-specific skills with the actual integration patterns. Running base-only twice doesn't load the missing skills; only --family <name> does. Skipping the flag here causes the agent to write integration code from training memory instead of from the framework-specific skills, which produces real bugs (e.g. the minHeight: 0 flex-shrink trap in cometchat-react-patterns rule 6a — only in that skill).

If framework is angular AND cometchat-angular-core is NOT loaded:

npx @cometchat/skills add --family angular

If framework is android AND neither cometchat-android-v5-core nor cometchat-android-v6-core is loaded:

npx @cometchat/skills add --family android

This installs both V5 and V6 skill sets — the dispatcher's Step 4 routing picks the correct one based on android_version.

If framework is flutter AND neither cometchat-flutter-v5-core nor cometchat-flutter-v6-core is loaded:

npx @cometchat/skills add --family flutter

Same shape as Android — installs both V5 and V6 skill sets; routing picks the right one based on flutter_version.

If framework is ios AND cometchat-ios-core is NOT loaded:

npx @cometchat/skills add --family ios

iOS only ships V5 today (no V6 beta yet), so there's no version-detection step — the install command lands the single iOS skill set.

After the install completes, tell the user:

"I just installed the {family} pattern skills into your workspace. Please re-run /cometchat to continue — your config is saved in .cometchat/config.json and credentials in .env, so the next run picks up at code generation without re-asking the questions you've already answered."

Why re-run rather than continue in this session: Claude Code, Cursor, Cline, Kiro, and other modern AI coding agents snapshot the skill set at session start and do NOT hot-reload SKILL.md mid-session. Even though the install writes the new skill files into .claude/skills/ (or .cursor/skills/ / .kiro/skills/ / .agents/skills/ — your agent's skills dir), your in-context skill set is the snapshot. Continuing would mean writing code from training memory — which the skills explicitly forbid (this is the same failure mode that produced the UIKitSettingsBuilder and getLoggedinUser casing bugs at v2.2.0). The re-run is the only safe path.

Non-default IDE — pass --ide. The default installer target is claude (.claude/skills/). If the dispatcher's own SKILL.md was loaded from a different location, pass the matching flag:

Dispatcher loaded from	Install command
.claude/skills/cometchat/SKILL.md (default)	npx @cometchat/skills add
.agents/skills/cometchat/SKILL.md (Replit / Cursor / Copilot / Cline / Codex)	npx @cometchat/skills add --ide replit
.cursor/skills/cometchat/SKILL.md (legacy Cursor path)	npx @cometchat/skills add --ide cursor
.kiro/skills/cometchat/SKILL.md	npx @cometchat/skills add --ide kiro

You can usually infer the IDE from where the dispatcher itself was loaded. If uncertain, default to claude. (Same logic applies to @cometchat/skills-native for RN projects.)

Do NOT attempt to write web UI Kit code into an RN project (CSS imports + <a href> + document.* fail at runtime) or RN UI Kit code into a web project (react-native-gesture-handler, @gorhom/bottom-sheet, native bubble components have no browser equivalents). Likewise, never use the React UI Kit (@cometchat/chat-uikit-react) in an Angular project — it's a different package (@cometchat/chat-uikit-angular) with NgModule imports, kebab-case selectors, content-projection slots, and no React reconciler. And never mix V5 and V6 skill sets within Android or Flutter — the artifact coordinates, package names, state-management primitives (V5 GetX vs V6 Bloc on Flutter; V5 Java/Views vs V6 Compose+Kotlin on Android), and theme system differ; the skills target one cohort each.

Step 2 — Set up credentials (onboarding)

CRITICAL: All onboarding happens via CLI commands. NEVER send the user to a browser or dashboard for credential copy-pasting. The CLI handles signup, login, app creation, and credential writing — all from the terminal — for every framework.

Hard rule — signup flows MUST ask, not infer

For Sign-Up paths specifically (Step 2b → 2b.5 → 2b.6 → 2c), the following structured prompts are NON-NEGOTIABLE and MUST be rendered via AskUserQuestion:

Prompt	When	Skipped only if
Role (Step 2b.6)	After auth me if meta.role === null	auth me returned a non-null role
Intent (Step 2b.6)	After auth me if meta.intent === null	auth me returned a non-null intent
App name (Step 2c)	Before provision setup	NEVER — even if a suggested default exists, user must explicitly confirm
Region (Step 2c)	Before provision setup	last_app.region exists AND user accepted the "use same region?" confirmation
Industry (Step 2c)	Before provision setup	last_app.industry exists AND user accepted the "same industry?" confirmation
Product (Step 3.0 Tier 3)	After Step 2c if Tier 1 (auth me last_app.product) AND Tier 2 (natural-language inference from slash-command + prior turn) both returned null	Tier 1 OR Tier 2 resolved a non-null value

Auto-mode classifiers do NOT authorize bypassing these prompts. "Allowed by auto mode classifier" applies to Bash/tool approvals — it does NOT apply to structured user prompts. The agent must surface each prompt regardless of approval mode. Rationalizations like "fresh test scaffold = just exploring, skip the prompt" or "moving forward without stops for the demo" are explicit spec violations — the dashboard's /select-product + /create-app + /choose-role + /choose-intent flows ask these in the browser; the CLI flow MUST ask them in the terminal for parity. Skipping them silently picks defaults that affect downstream Step 3a (intent → archetype) and Step 3b.1 (industry → recommendation upsells) — the user can't correct values they never saw asked.

If config has appId set, verify credentials are in .env and skip to Step 3.

Otherwise check:

npx @cometchat/skills-cli auth status --json

If status is "logged-in", skip to Step 2b.5 (fetch dashboard profile).

If status is "logged-out", ask:

Ask the user (preserve this exact shape — question, header, multiSelect, options[].label, options[].description — agents have varying primitive names but they all support this structured form):

• question: "Let's set up CometChat. Do you have an account?"
• header: "Account"
• multiSelect: false
• options:
  1. label: "Create a new account", description: "Free signup — I'll handle it right here, no browser needed."
  2. label: "Sign in to existing account", description: "Log in and pick one of your apps."
  3. label: "I'll paste credentials myself", description: "I already have my App ID, Region, and Auth Key."

Option 1 → Step 2b. Option 2 → Step 2a. Option 3 → Step 2d.

Step 2a — Sign in (existing account, browser flow)

npx @cometchat/skills-cli auth login

This command:

1. Generates a short-lived session via the CLI auth API.
2. Opens https://app.cometchat.com/login?sessionId=<hex> in the user's default browser.
3. Polls the auth API every 5 seconds for up to 15 minutes.
4. When the user finishes signing in, the dashboard marks the session authenticated. The next poll receives the bearer token and stores it in the OS keychain.
5. Prints ✓ Logged in as <email> (backend: keychain-macos).

Let the CLI block — do NOT background it, do NOT race it with other prompts.

Terminal error handling (surface verbatim, stop, do not retry silently):

• ACCESS_DENIED — user clicked Deny in the dashboard.
• EXPIRED — 15-minute window elapsed.
• TIMEOUT — max polls exhausted before user authorized.
• ABORTED — user Ctrl-C'd the CLI.
• NETWORK — couldn't reach the auth host.
• ALREADY_AUTHENTICATED — this session was already consumed. Re-run auth login to mint a fresh session.
• AUTH_FAILED — the bearer was rejected (401) — e.g. a stored token expired or was revoked, surfaced by a later auth me / auth status. Re-run auth login to re-authenticate. (Distinct from the device-auth codes above: this is the post-login "my session went stale" case, normalized from a 401 in cometchat-api.ts.)
• API_ERROR:<code> (and any unlisted code) — an unexpected server-side error; do NOT pattern-match it. Fall through to the generic handler: show the CLI's human_message / suggestion if present, then the raw error in parentheses (see the error-handling rule near the end of this skill).

After success, verify via auth status --json and proceed to Step 2b.5.

Step 2b — Sign up (new account, browser flow)

npx @cometchat/skills-cli auth signup

Same polling flow as Step 2a, but the CLI opens the signup URL. The browser handles email, name, password, verification email, role, industry. The CLI never sees any of those values.

No role / name / verification-code questions in the chat. The dashboard owns that flow now; skipping it keeps the user's password and verification code out of the transcript.

Error codes match Step 2a. After success, verify via auth status --json and proceed to Step 2b.5.

Step 2b.5 — Fetch the user's dashboard profile

The dashboard's signup flow (/auth/signup → /choose-role → /choose-intent) collects the user's name, email, role, and product intent during browser onboarding — none of those values touch the CLI. Now that the bearer token is in the keychain, fetch them via cometchat auth me so the rest of this skill can:

• Greet the user by name in subsequent steps
• Skip the placement-intent question (Step 3a) when meta.intent === "exploring" (the user already told the dashboard they're just exploring)
• Tailor explanation depth by meta.role (frontend developer → UI examples; engineering manager → architecture trade-offs)

npx @cometchat/skills-cli auth me --json

Response shape:

{
  "status": "logged-in",
  "email": "[email protected]",
  "name": "Your Name",
  "role": "frontend",
  "other_role": null,
  "intent": "building",
  "last_app": {
    "id": "27xxxxx",
    "name": "my-marketplace-chat",
    "region": "us",
    "industry": "online_marketplaces",
    "technology": "react",
    "product": "chat-messaging"
  }
}

Field meanings (from the dashboard's signup screens):

• role: "frontend" / "backend" / "fullstack_engineer" / "startup_founder" / "product_leader/manager" / "engineering_leader/manager" / "others" (when others, other_role carries the freeform value)

• intent: "building" / "evaluating" / "exploring" (this is the dashboard's intent — distinct from Step 3a's placement_intent which asks about app archetype)

• last_app: most-recently-created app on the user's account (or null if they have none). The dashboard's /create-app and /select-product screens write industry, technology, product into the app's metadata — we surface them here so Step 2c can pre-fill region/industry instead of asking again.

• last_app.product: the surface the user picked on the dashboard's /select-product screen — "chat-messaging" / "voice-video" / "ai-agent" / "byo-agent" / null. Load-bearing for Step 3.0 — it decides which dispatcher (chat or calls) handles the integration. chat-messaging runs the existing chat flow; voice-video hands off to cometchat-calls; ai-agent and byo-agent are out of scope for /cometchat today and point at the AI Agents docs.

  Dashboard ↔ canonical mapping (load-bearing — wired in cometchat-api.ts:listApps):

  Dashboard metadata.features	Canonical last_app.product
  chat	chat-messaging
  calling	voice-video
  aiAgent	ai-agent
  byo-agent	byo-agent

  The dashboard's /select-product is single-select and writes metadata.features = "<dashboard-key>"; the CLI maps it to canonical at the API boundary so downstream code only sees canonical values. If dashboard sends an unknown key (e.g. moderation), product is left undefined and Step 3.0 infers from natural language or asks at routing time.

  The combined value chat-messaging+voice-video is CLI-only — surfaced in Step 3.0's prompt as "Both Chat and Calling" when inference can't tell. The dashboard picker doesn't expose "Both" today.

Store the response in working memory. Reference these fields downstream:

• Step 2c (new app): if last_app is non-null, default --region and --industry to the values from last_app and only ask the user to confirm — do NOT re-prompt from scratch.
• Step 3.0 (product branch): route by last_app.product. chat-messaging continues into Step 3a; voice-video short-circuits to the cometchat-calls dispatcher; ai-agent and byo-agent exit with a docs pointer.
• Step 3a: if meta.intent === "exploring", skip the placement-intent question and route straight to the "Just exploring" branch (one route/screen with <CometChatConversations /> and cometchat-uid-1 pre-logged-in).
• Step 3b.1 (industry tailoring): use last_app.industry to layer industry-specific upsells onto the placement recommendation — moderation features for dating apps, HIPAA-aware production patterns for healthcare, link-preview for marketplaces, etc. Augment, don't replace.
• Step 5 explanations: if meta.role === "frontend", lead with concrete component composition + CSS examples; if meta.role === "engineering_leader/manager", lead with placement architecture trade-offs (where state lives, what gets cached, how routing fits the project's pattern).
• Greeting: if meta.name is non-null, greet by name in any user-facing message during the rest of the flow ("Got it, {name} — let's pick an app").

Failure modes — each is non-blocking; degrade to the original generic flow:

• status: "logged-out" → bearer expired between Step 2a/b and now (rare). Re-run auth login and retry.
• status: "auth-required" → 401 from server. Same fix.
• status: "error" → network or unexpected. Skip silently, proceed to Step 2b.6 (will ask role + intent there).
• name is null → no greeting (don't ask, the dashboard will collect it on next browser visit).
• role is null → ask in Step 2b.6 (this is the case for accounts that signed up via auth signup from the CLI — they never saw the dashboard's /choose-role screen).
• intent is null → ask in Step 2b.6.
• last_app.product is null (or last_app itself is null) → resolved in Step 3.0 via natural-language inference, falling back to a prompt only if ambiguous. Do NOT ask product upfront in Step 2b.6 — the dashboard's /select-product is a structured form because a UI can't read intent; the agent flow can.
• last_app is null → ask region/industry normally in Step 2c.

After this step, proceed to Step 2b.6.

Step 2b.6 — Backfill role + intent if missing

The dashboard's /choose-role and /choose-intent screens collect two profile fields used to tailor the rest of the integration:

• role shapes the depth and angle of code explanations in Step 5
• intent decides whether Step 3a's placement question is needed (exploring short-circuits to a single screen)

(product is resolved separately in Step 3.0 via natural-language inference + lazy ask — not here.)

If auth me returned non-null values for both, skip this step entirely and go to Step 2c — the dashboard already collected them, do not re-ask.

If either is null (typical for accounts created via cometchat auth signup rather than the dashboard browser flow), ask the user. The options below mirror the dashboard exactly so anyone who later visits the dashboard sees consistent terminology.

If role === null — ask the user (preserve the structured shape — question/header/multiSelect/options[].label/options[].description — agents have varying primitive names but all support this form):

• question: "What's your role? (We'll tailor explanations to match.)"

• header: "Role"

• multiSelect: false

• options (label → store as role value):

  Label	role value
  Frontend Developer	frontend
  Backend Developer	backend
  Fullstack Developer	fullstack_engineer
  Founder	startup_founder
  Product Manager	product_leader/manager
  Engineering Manager	engineering_leader/manager
  Other	others

  If the user picks Other, follow up with a free-form question for other_role (single short text field; store the freeform value in other_role).

If intent === null — ask the user (preserve the structured shape):

• question: "What brings you to CometChat?"

• header: "Intent"

• multiSelect: false

• options (use the dashboard's exact wording):

  Label	Description shown under the label	intent value
  I'm building	Integrating chat into my app now.	building
  I'm evaluating	Comparing options for my team.	evaluating
  I'm exploring	Just looking around for now.	exploring

Do NOT ask for product in this step. The dashboard's /select-product is a structured form because a UI can't read intent; the CLI/agent flow is conversational and the user has often already said what they want. Asking upfront ("Chat & Messaging? Voice & Video? Both?") is friction the dashboard has but the agent doesn't need.