> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-pin-save-docs-reframe.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Build CometChat with AI Agent Skills
> Install the CometChat agent skills so your AI coding agent (Claude Code, Cursor, GitHub Copilot, Replit, and more) can add production-grade chat and calling to your React, Angular, React Native, iOS, Android, or Flutter app from natural-language prompts.
**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](https://app.cometchat.com) to get an app's App ID, Region, and Auth Key.
* An **existing app** on one of the [supported platforms](#supported-platforms).
* One of the [supported AI coding agents](#supported-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](#building-your-own-ui).)
## Install
Run the installer in your project root:
```bash theme={null}
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`:
```bash theme={null}
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](/cli)
— 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:
```bash theme={null}
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 ` **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](https://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](#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](https://www.cometchat.com/contact-sales). Choose it if you can't take
a maintenance window.
See [Data Import and Migration](/fundamentals/data-import-and-migration) for both
approaches, and the [Data Import API](/rest-api/data-import) 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](/rest-api/auth-tokens) 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 `. 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](#connect-your-credentials) 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
Connect CometChat to any Model Context Protocol–compatible agent
Fetch credentials and manage the skills from your terminal
The manual React setup the skills automate
The manual Angular setup the skills automate
The manual React Native setup the skills automate
The manual iOS setup the skills automate
The manual Android setup the skills automate
The manual Flutter setup the skills automate