Build CometChat with AI Agent Skills

CometChat Agent Skills teach your AI coding agent how to build with CometChat. Install the skills once, then open your project and say “add chat to my app” — the agent has a short conversation with you (framework, intent, placement, credentials), then writes production-grade integration code directly into the files you already have. The skills cover six UI Kits — React v7, Angular v5, React Native v5, iOS v5, Android v6, and Flutter v6. They author against the official CometChat task guides and verify their output against them, so what the agent writes builds and runs against the current published UI Kit — not a hallucinated API.

The skills work inside your existing project with your existing agent. They don’t scaffold a throwaway demo — they detect your setup and integrate CometChat into the app you’re already building.

Prerequisites

Node.js 18+ — the installer runs through npx, so there’s nothing to install globally.
A CometChat account — sign up free to get an app’s App ID, Region, and Auth Key.
An existing app on one of the supported platforms.
One of the supported AI coding agents below.

Supported platforms

Platform	UI Kit
React 18+ — Vite, Create React App, Next.js, React Router, Astro	React UI Kit v7
Angular — Angular CLI or Nx	Angular UI Kit v5
React Native — bare or Expo	React Native UI Kit v5
iOS — Swift, Swift Package Manager	iOS UI Kit v5
Android — Jetpack Compose or Kotlin (Views)	Android UI Kit v6
Flutter	Flutter UI Kit v6

The installer detects your platform from the project — you don’t tell it which one. If it can’t detect a supported setup (for example at a monorepo root), it tells you instead of guessing; run add inside the app’s folder. (The one time you name a platform yourself is the headless SDK skills.)

Install

Run the installer in your project root:

npx @cometchat/skills add

It detects your platform, installs that platform’s skills, and installs them for Claude Code by default. It also connects the CometChat Docs MCP server (cometchat-docs) for that agent; pass --no-mcp to skip it. In Claude Code, approve cometchat-docs when claude asks on first start in the project — until then claude mcp list shows it as Pending approval, and the skills fall back to the docs site. To install for a different agent, pass --ide:

npx @cometchat/skills add --ide claude    # Claude Code   → .claude/skills/
npx @cometchat/skills add --ide cursor    # Cursor        → ./.cometchat/skills + router
npx @cometchat/skills add --ide replit    # Replit Agent  → .agents/skills/
npx @cometchat/skills add --ide all       # every supported agent

Supported agents

Agent	Install with
Claude Code	`--ide claude`
Cursor	`--ide cursor`
Kiro	`--ide kiro`
Antigravity	`--ide antigravity`
GitHub Copilot	`--ide copilot`
Replit Agent	`--ide replit`
Codex	`--ide codex`
Gemini	`--ide gemini`
Windsurf	`--ide windsurf`
Cline	`--ide cline`
Continue	`--ide continue`
Aider	`--ide aider`

Claude Code, Kiro, and Replit get a native SKILL.md tree. The other agents get an orienting router plus a ./.cometchat/skills tree. Add --global (Claude Code only) to install into your user-level ~/.claude/skills instead of the project.

Use it

Open your project in your agent and prompt it:

add chat to my app

or type the dispatcher directly:

/cometchat

The cometchat dispatcher detects your platform and routes to cometchat-onboarding, which walks a short discover → understand → plan → approve flow. Once you approve the plan, it hands a scoped build directive to your platform’s core skill (for example cometchat-react-v7-core, cometchat-ios-core, or cometchat-flutter-v6-core) and pulls in the other skills as the plan needs them (components, placement, theming, features, calls, push). Keep iterating in plain language afterward:

“Add message reactions and threaded replies.”
“Switch the chat to dark mode and match my brand color.”
“Add a group details side panel.”
“Set up production authentication.”

Connect your credentials

You usually don’t have to paste your App ID / Region / Auth Key by hand. During the build, when the skill notices they’re missing, it offers two paths and defaults to fetching them from your dashboard:

Fetch from your dashboard (recommended) — the skill runs the standalone CometChat CLI for you, on demand: it opens the dashboard login in your browser, lets you pick one of your existing apps, pulls the credentials, and writes a neutral .cometchat/config.json. You can also run the CLI yourself — it works on its own, in a script, or in CI.
Paste manually — copy App ID, Region, and Auth Key from Dashboard → Your App → Credentials if you’d rather not log in.

Either way, the skill then writes your platform’s config from those credentials — the CLI only fetches them and never touches your app code:

Platform	Where the credentials go
React	`.env` (`.env.local` for Next.js) with your bundler’s prefix: `VITE_` / `REACT_APP_` / `NEXT_PUBLIC_` / `PUBLIC_`
Angular	`src/environments/environment.ts`
React Native	`.env`
iOS	`Secrets.xcconfig`
Android	`app/src/main/assets/cometchat-settings.json`
Flutter	`cometchat-settings.json` (a registered asset)

Keep credentials out of version control. Both .cometchat/config.json and the generated credentials file contain your Auth Key. Make sure they’re in .gitignore — for example, Vite, CRA, and Astro ignore only *.local (not .env), so add .env yourself. The Auth Key is for development only: in production, mint a short-lived per-user auth token on your backend and log in with it (loginWithAuthToken() on web) — never ship the Auth Key to a production client.Flutter is the exception: cometchat-settings.json is a registered asset, so a missing file breaks flutter build on a fresh clone. Don’t gitignore it — commit a placeholder with an empty authKey, and fill in the real credentials locally and at build time.

What’s in the pack

Task-shaped skills the agent loads on demand. add installs the shared skills plus the skill set for your platform only, so one platform’s skills never answer another platform’s prompts. Shared skills (installed for every platform)

Skill	Purpose
`cometchat`	Thin dispatcher — detect the platform and route
`cometchat-onboarding`	Discover → understand → plan → approve (the front door)

Platform skills Every UI Kit platform ships a core skill (install · credentials · init → login → render · the golden-path chat surface) plus the task skills below. The set differs per platform:

Platform	Skill prefix	Skills
React v7	`cometchat-react-v7-`	`core` · `components` · `placement` · `customization` · `patterns` · `features` · `calls` · `push` · `migration`
Angular v5	`cometchat-angular-v5-`	`core` · `components` · `placement` · `customization` · `patterns` · `features` · `calls` · `push` · `production` · `testing` · `troubleshooting` · `migration`
React Native v5	`cometchat-react-native-`	`core` · `components` · `placement` · `customization` · `expo-patterns` · `bare-patterns` · `features` · `calls` · `push` · `production` · `testing` · `troubleshooting` · `migration` · `sdk`
iOS v5	`cometchat-ios-`	`core` · `components` · `placement` · `customization` · `features` · `calls` · `push` · `migration`
Android v6	`cometchat-android-v6-`	`core` · `compose-components` · `compose-placement` · `compose-customization` · `kotlin-components` · `kotlin-placement` · `kotlin-customization` · `features` · `calls` · `push` · `production` · `testing` · `troubleshooting` · `builder-settings` · `events` · `extensions` · `migration`
Flutter v6	`cometchat-flutter-v6-`	`core` · `components` · `placement` · `customization` · `patterns` · `features` · `calls` · `push` · `production` · `testing` · `troubleshooting` · `events` · `migration`

Building your own UI

Want voice/video calling without a UI Kit? The headless Calls SDK v5 skills — and the headless Android Chat SDK v5 skill — aren’t installed by add on its own. Ask for them with --family, which adds them next to your platform’s UI Kit skills:

npx @cometchat/skills add --family js-calls   # headless JS Calls SDK skills

Headless skill	Install with
`cometchat-js-v5-sdk` — Calls SDK, JavaScript	`--family js-calls`
`cometchat-react-native-v5-sdk` — Calls SDK, React Native	`--family react-native-calls`
`cometchat-ios-v5-sdk` — Calls SDK, iOS	`--family ios-calls`
`cometchat-android-v5-calls-sdk` — Calls SDK, Android	`--family android-calls`
`cometchat-flutter-v5-sdk` — Calls SDK, Flutter	`--family flutter-calls`
`cometchat-android-v5-sdk` — Chat SDK, Android	`--family android-sdk`

If you ask for calling-only in a project without a UI Kit, onboarding walks you through the choice and tells you which of these to install.

Two things to know about the Android rows: --family android-sdk and --family android-calls share the cometchat-android-v5- folder, so installing either brings in both the Android Chat SDK and Calls SDK skills.And for the router-file agents (every agent other than Claude Code, Kiro and Replit), the managed router block in AGENTS.md (and the equivalent files) always points to the last family you installed. --family takes a single value and replaces detection, so it can’t be combined with your platform in one run — after a --family run, re-run npx @cometchat/skills add --ide <agent> without --family to point the block back at your UI Kit skills. The skill folders in .cometchat/skills are additive, so the calls skills stay installed either way.

What the task skills do:

Skill	Purpose
`components`	The UI Kit component catalog + props / inputs / slots
`placement`	Where chat lives — full screen, sidebar, popup, embedded panel, navigation
`customization`	Theming · brand · light/dark · view slots
`patterns`	Framework glue — e.g. Vite / Next.js / React Router / Astro, Angular CLI / Nx, Expo vs bare React Native
`features`	Enable a feature — reactions · polls · AI · moderation · …
`calls`	Voice / video calling with the UI Kit
`push`	Push notifications (Notifications product)
`production`	Server-minted auth tokens · hardening before you ship (Angular, React Native, Android, Flutter)
`testing` · `troubleshooting`	Test an app that embeds CometChat · diagnose a broken integration (Angular, React Native, Android, Flutter)
`migration`	Upgrade from the previous UI Kit major

Example prompts

Everything starts from one prompt — “add chat to my app” — then you refine in plain language. Example prompts, grouped by goal: Get started

“Add chat to my app.” — the default: a conversation list + message view
“Add 1:1 direct messaging between my users.”
“Add group chat with file sharing.”
“Build a full chat app with Chats, Users, and Calls tabs.”

Where chat lives

“Add a support chat widget in the bottom-right corner.”
“Add a floating chat popup I can toggle open and closed.”
“Put chat in a sidebar next to my app.”
“Embed a chat panel on my dashboard page.”

Features

“Add message reactions, typing indicators, and read receipts.”
“Add threaded replies and @mentions.”
“Add image and file sharing.”
“Add message search.”
“Add polls and stickers.”

Calling & AI

“Add voice and video calling with a click-to-call button.”
“Add smart replies and conversation summaries.”
“Add an AI assistant to the chat.”
“Turn on moderation so banned words are blocked before delivery.”

Look & feel

“Switch the chat to dark mode and match my brand color.”
“Make the chat follow the user’s system light/dark setting.”

Ship it

“Set up production authentication with auth tokens.”
“Add web push notifications.”
“Upgrade my app to the latest UI Kit version.”

The agent plans each change with you, then writes the integration into your existing files — you don’t have to know the component or prop names.

Migrate from another chat provider

Already using a different chat provider and want to move to CometChat? One prompt does the whole thing. (Already on CometChat and upgrading the UI Kit instead? That’s a different job — say “Upgrade my app to the latest UI Kit version” from the section above.)

“Migrate my app to CometChat.”

The agent detects the provider you’re on and migrates your app end to end in one run: it swaps the data layer (or your UI components) over to CometChat, wires init → login, maps every feature that has a CometChat equivalent, removes the ones that don’t (and lists them for you), and verifies the build. Your own UI is preserved when you built on the provider’s SDK; the CometChat UI Kit takes over where you used the provider’s UI Kit.

Before you start

Create your CometChat app first, and put its credentials in place. Sign up at app.cometchat.com and create an app — the migration never creates one for you. It also won’t ask you for your app credentials: it reads them from .cometchat/config.json or your environment, and writes placeholders (with an “add your credentials” action item) if it finds neither. So set them up first — see Connect your credentials — or you’ll get a build full of placeholders to fill in later.
Create a full-access REST API key for the history import. Unlike the app credentials, the agent does ask you for this one (and your current provider’s key) when it runs the import.
Node.js 18 or newer, for npx and the data-import script.
Your app should build today on your current provider — migrating an app that doesn’t build first only hides which errors were yours.
Start from a clean git branch. The agent works on a new cometchat-migration branch and never commits, so the diff stays easy to review.

Safe to run on a real repo: it works on its own branch and never commits, and it never deletes your own app code — where your code shares a file with the provider’s, it’s rewired, not removed. To leave no trace of the old provider it does go beyond deleting SDK calls, though: it updates your README, setup/deploy guides and .env.example to describe CometChat, renames provider-named identifiers (e.g. providerUserId → userId), and removes docs that describe the old provider’s product (its changelog or docs pages). Review the branch diff before you merge.

Bringing your history across

The migration also prepares a data-import script for your users, groups and messages. When the app migration is done, the agent tells you the script is ready for data import and asks for your API keys (or the relevant credentials) — for both your current provider and your CometChat app. Once you provide them, the agent runs the import for you — a dry run first, showing the users, groups, members and messages it will import, then the real import. You don’t run anything by hand.

CometChat retains messages for the last 6 months by default, so the import brings over history from that window. To import messages older than 6 months, reach out to CometChat and we’ll help you import the older history.

Choosing a cut-over strategy

Hard switch (default). Export from your current provider, import into CometChat, then deploy the migrated app. Simplest — do it in a maintenance window so no messages are sent mid-copy. The generated script does exactly this.
Zero-downtime live migration. Keep both systems in sync while users move onto the new build gradually. This one is set up with CometChat’s team — contact sales. Choose it if you can’t take a maintenance window.

See Data Import and Migration for both approaches, and the Data Import API for the limits the import script respects.

Before you go live

Switch login from the development Auth Key to server-minted auth tokens. The Auth Key is for development only; in production your server mints a per-user auth token and the client logs in with loginWithAuthToken(). The agent leaves this as an action item and, where your app already has a token server, wires it for you.

Manage the skills

Update — re-run npx @cometchat/skills add to pull the latest skills; it overwrites the installed skill tree in place.
Inspect — npx @cometchat/skills list lists the skills the pack ships, and npx @cometchat/skills doctor runs an environment health check.
Uninstall — there’s no uninstall command. Remove what add wrote for your agent:
- The skill files — .claude/skills/cometchat* (Claude Code), .kiro/skills/cometchat* (Kiro), .agents/skills/cometchat* (Replit), or ./.cometchat/skills (every other agent). For Claude Code, Kiro, and Replit, also delete the shared files add puts at the top of that folder: RULES.md, peers.yaml, catalogs/, and the features*.json / contracts*.json files. For a --global install, use ~/.claude/skills instead.
- The router block — for the other agents, add also writes a block between  and  into the agent’s instruction file: AGENTS.md (Cursor, Codex, Antigravity, Continue), .github/copilot-instructions.md (Copilot), GEMINI.md (Gemini), .windsurfrules (Windsurf), .clinerules/cometchat.md — or .clinerules itself when you already have that as a file — (Cline), or CONVENTIONS.md (Aider). Delete that block and keep the rest of the file.
- The Docs MCP entry — remove the cometchat-docs server from .mcp.json (Claude Code), .cursor/mcp.json (Cursor), .gemini/settings.json (Gemini), or .codex/config.toml (Codex). For a --global Claude Code install, run claude mcp remove --scope user cometchat-docs. Other agents get no MCP entry.
Version control — commit the skill files so your whole team shares the same setup. Do not commit .cometchat/config.json or the generated env file — they hold your Auth Key. (Flutter is the exception: commit the cometchat-settings.json placeholder with an empty authKey, as noted above — a missing asset breaks flutter build — and keep the real credentials local.)

Troubleshooting

Symptom	Likely cause	Fix
The agent doesn’t pick up the skills	Installed for a different agent, or a router-based agent needs pointing at the tree	Re-run `npx @cometchat/skills add --ide <your-agent>`. For router agents (Cursor, Copilot, …) open `.cometchat/skills/cometchat/SKILL.md` to orient it.
Blank screen, no errors	A UI Kit component rendered before `init` + `login` resolved, or the credentials weren’t picked up	The `init → login → render` order is required. Check that the Region matches your dashboard app and that the app reads the credentials file for your platform (on React, the env prefix must match your bundler: `VITE_` / `REACT_APP_` / `NEXT_PUBLIC_` / `PUBLIC_`).
`login()` fails — “user not found”	Logging in a UID that doesn’t exist in the app	Use a UID that exists (Dashboard → your app → Users; fresh apps seed `cometchat-uid-1`).
Auth error on init / login	Region mismatch between your code and the dashboard app	Re-check the Region (`us` / `eu` / `in`) in both the dashboard and your env file.
`ERROR_API_KEY_NOT_FOUND`	A credential is empty or not picked up by the build	Confirm the credentials file for your platform is filled in (on web, with the right env prefix for your bundler), then rebuild or restart the dev server.
Version conflict during install	An older UI Kit major is already installed (for example React v6 or Android v5)	Ask the agent to migrate — your platform’s `migration` skill upgrades it to the version the skills target.

Compatibility

Platform	Packages
React v7	`@cometchat/chat-uikit-react` `7.x` (verified 7.1.x) · `@cometchat/chat-sdk-javascript` `4.x` · `@cometchat/calls-sdk-javascript` `5.x` (calling) · React `≥ 18`
Angular v5	`@cometchat/chat-uikit-angular` `5.x` (verified 5.1.0) · `@cometchat/chat-sdk-javascript` `^4.1.13` · `@cometchat/cards-angular` `^1.0.0` · `@cometchat/calls-sdk-javascript` `^5.0.3` (calling) · `dompurify` `^3.0.0`
React Native v5	`@cometchat/chat-uikit-react-native` `5.x` · `@cometchat/chat-sdk-react-native` `4.x` · `@cometchat/calls-sdk-react-native` `5.x` (calling)
iOS v5	`CometChatUIKitSwift` `5.1.x` · `CometChatSDK` `4.1.x` · `CometChatCallsSDK` `5.0.x` (calling) — Swift Package Manager
Android v6	`com.cometchat:chatuikit-compose-android` or `chatuikit-kotlin-android` `6.0.x` · `chat-sdk-android` `5.0.x` · `calls-sdk-android` `5.0.x` (calling)
Flutter v6	`cometchat_chat_uikit` `^6` (verified 6.1.x) · `cometchat_calls_sdk` `^5` (calling)

Next steps

MCP Integration

Connect CometChat to any Model Context Protocol–compatible agent

CometChat CLI

Fetch credentials and manage the skills from your terminal

React UI Kit

The manual React setup the skills automate

Angular UI Kit

The manual Angular setup the skills automate

React Native UI Kit

The manual React Native setup the skills automate

iOS UI Kit

The manual iOS setup the skills automate

Android UI Kit

The manual Android setup the skills automate

Flutter UI Kit

The manual Flutter setup the skills automate

​Prerequisites

​Supported platforms

​Install

​Supported agents

​Use it

​Connect your credentials

​What’s in the pack

​Building your own UI

​Example prompts

​Migrate from another chat provider

​Before you start

​Bringing your history across

​Choosing a cut-over strategy

​Before you go live

​Manage the skills

​Troubleshooting

​Compatibility

​Next steps

MCP Integration

CometChat CLI

React UI Kit

Angular UI Kit

React Native UI Kit

iOS UI Kit

Android UI Kit

Flutter UI Kit

Prerequisites

Supported platforms

Install

Supported agents

Use it

Connect your credentials

What’s in the pack

Building your own UI

Example prompts

Migrate from another chat provider

Before you start

Bringing your history across

Choosing a cut-over strategy

Before you go live

Manage the skills

Troubleshooting

Compatibility

Next steps