> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-cli-section.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 and let your AI coding agent — Claude Code, Cursor, GitHub Copilot, Replit, and more — add production-grade chat and calling to your React 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 author against the official **React UI Kit v7** 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 React app** on React 18 or newer. Supported setups: **Vite**, **Create React App**, **Next.js**, **React Router**, and **Astro**.
* One of the [supported AI coding agents](#supported-agents) below.
The skills target the **React UI Kit v7** today. The installer tells you if it
can't detect a supported React setup — it never guesses or scaffolds a throwaway
project.
## Install
Run the installer in your project root:
```bash theme={null}
npx @cometchat/skills add
```
It detects your React setup and opens a picker to install the skills for the AI
agent(s) you use. To pin a single agent — useful in CI or a Dockerfile — 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` |
| GitHub Copilot | `--ide copilot` |
| Windsurf | `--ide windsurf` |
| Replit Agent | `--ide replit` |
| Cline | `--ide cline` |
| Codex | `--ide codex` |
| Gemini | `--ide gemini` |
| Continue | `--ide continue` |
| Aider | `--ide aider` |
| Kiro | `--ide kiro` |
| Antigravity | `--ide antigravity` |
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, Kiro, and Replit only) to install into your user-level directory 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 React 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 `cometchat-react-v7-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 don't 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 **installs and runs the
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 don't install or run the CLI
yourself.
* **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 the framework env file (`.env` / `VITE_` /
`NEXT_PUBLIC_` …) from those credentials — the CLI only fetches them and never
touches your framework code.
**Keep credentials out of version control.** Both `.cometchat/config.json` and
the generated env file contain your **Auth Key**. Make sure they're in
`.gitignore` — Vite, CRA, and Astro ignore only `*.local` (not `.env`), so add
`.env` yourself; Next.js ignores `.env.local` by default. The Auth Key is for
**development only**: in production, mint a short-lived per-user **auth token** on
your backend and log in with `loginWithAuthToken()` — never ship the Auth Key to
a production client.
Prefer to drive it yourself? The credential CLI is also a standalone tool —
`npx @cometchat/skills-cli auth login`, then `provision run`. See the
[CLI reference](/cli) for the full command surface.
## What's in the pack
Eleven task-shaped skills the agent loads on demand:
| Skill | Purpose |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| `cometchat` | Thin dispatcher — detect React and route |
| `cometchat-onboarding` | Discover → understand → plan → approve (the front door) |
| `cometchat-react-v7-core` | Install · credentials · init → login → render · the golden-path chat surface |
| `cometchat-react-v7-components` | The v7 component catalog + props / slots |
| `cometchat-react-v7-placement` | Where chat lives — full app / sidebar / popup / embed |
| `cometchat-react-v7-customization` | Theming · brand · light/dark · view slots |
| `cometchat-react-v7-patterns` | Vite / Next.js / React Router / Astro glue (env · SSR · routing) |
| `cometchat-react-v7-features` | Enable a feature — reactions · polls · AI · moderation · … |
| `cometchat-react-v7-calls` | Voice / video calling |
| `cometchat-react-v7-push` | Web push (Notifications product) |
| `cometchat-react-v7-migration` | Upgrade a v6 UI Kit → v7 |
## 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."*
* *"Migrate my v6 UI Kit to v7."*
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` shows the installed skills, and `npx @cometchat/skills doctor` runs an environment health check.
* **Uninstall** — delete the installed skill directory for your agent (for example `.claude/skills/cometchat*`, `.agents/skills/`, or `./.cometchat/skills`).
* **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.
## 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 wrong Region / env prefix | The `init → login → render` order is required. Check that the Region matches your dashboard app and the env prefix matches your bundler (`VITE_` / `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` | An env var is empty or not picked up by the bundler | Confirm the env file uses the right prefix for your bundler, then restart the dev server. |
| Version conflict during install | An older **v6** UI Kit is already installed | Ask the agent to migrate — the `cometchat-react-v7-migration` skill upgrades v6 → v7. |
## Compatibility
| Dependency | Version |
| --------------------------------- | ---------------------- |
| `@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` |
## Next steps
Authenticate, provision credentials, and manage the skills from your terminal
Connect CometChat to any Model Context Protocol–compatible agent
The manual React UI Kit setup the skills automate
Browse all prebuilt UI components