> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-agent-native-development.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.

<Note>
  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.
</Note>

## 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 |

<Note>
  **`--family` is optional — you normally don't pass it.** Run `add` **inside your app** and it detects
  your platform from the project automatically; you don't tell it which one. You only name the platform
  yourself when detection can't resolve one:

  * **A new/empty folder with no app yet (or the wrong directory).** The installer can't detect a
    framework, so it stops instead of guessing. Best fix: create your app and `cd` into it first, so the
    skills land in the project — then run `npx @cometchat/skills add` with no flag. Otherwise name the
    platform explicitly, e.g. `npx @cometchat/skills add --family react`. The skills install into
    the folder you run the command in, so run it inside your app's project folder.
  * **A monorepo root**, where the framework lives in a package rather than at the root — run `add`
    inside the app package, or pass `--family <platform>`.
  * **Headless SDK / calls skills**, which have no UI Kit to detect — see
    [Building your own UI](#building-your-own-ui).
</Note>

## Install

Run the installer in your app's folder (in a monorepo, the app package, not the repo 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` |

<Note>
  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.
</Note>

## 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) |

<Warning>
  **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.
</Warning>

## 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.

<Note>
  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.
</Note>

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.

## 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 `<!-- cometchat-skills:start -->` and `<!-- cometchat-skills:end -->` 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](#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

<CardGroup cols={2}>
  <Card title="MCP Integration" icon="plug" href="/mcp-server">
    Connect CometChat to any Model Context Protocol–compatible agent
  </Card>

  <Card title="CometChat CLI" icon="terminal" href="/cli">
    Fetch credentials and manage the skills from your terminal
  </Card>

  <Card title="React UI Kit" icon="react" href="/ui-kit/react/integration-react">
    The manual React setup the skills automate
  </Card>

  <Card title="Angular UI Kit" icon="angular" href="/ui-kit/angular/integration">
    The manual Angular setup the skills automate
  </Card>

  <Card title="React Native UI Kit" icon="mobile" href="/ui-kit/react-native/overview">
    The manual React Native setup the skills automate
  </Card>

  <Card title="iOS UI Kit" icon="apple" href="/ui-kit/ios/getting-started">
    The manual iOS setup the skills automate
  </Card>

  <Card title="Android UI Kit" icon="android" href="/ui-kit/android/getting-started">
    The manual Android setup the skills automate
  </Card>

  <Card title="Flutter UI Kit" icon="mobile-screen-button" href="/ui-kit/flutter/getting-started">
    The manual Flutter setup the skills automate
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.