Added CLI Docs

agent-skills.mdx

@@ -0,0 +1,249 @@
+---
+title: "Build CometChat with AI Agent Skills"
+sidebarTitle: "Agent Skills"
+description: "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."
+canonical: "https://www.cometchat.com/docs/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 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.
+
+<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 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.
+
+<Note>
+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.
+</Note>
+
+## Install
+
+Run the installer in your project root:
+
+```bash
+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
+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` |
+
+<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, Kiro, and Replit only) to install into your user-level directory 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 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.
+
+<Warning>
+**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.
+</Warning>
+
+<Note>
+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.
+</Note>
+
+## 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 <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 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
+
+<CardGroup cols={2}>
+  <Card title="CLI Reference" icon="terminal" href="/cli">
+    Authenticate, provision credentials, and manage the skills from your terminal
+  </Card>
+  <Card title="MCP Integration" icon="plug" href="/mcp-server">
+    Connect CometChat to any Model Context Protocol–compatible agent
+  </Card>
+  <Card title="React Integration" icon="react" href="/ui-kit/react/integration-react">
+    The manual React UI Kit setup the skills automate
+  </Card>
+  <Card title="Components Overview" icon="grid-2" href="/ui-kit/react/components-overview">
+    Browse all prebuilt UI components
+  </Card>
+</CardGroup>