@cometchat/skills 3.0.0

package/README.md

@@ -0,0 +1,112 @@
+# cometchat-skills
+
+**Add CometChat to any React project through your AI coding agent.** Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/vercel-labs/skills).
+
+v3 takes an AI-first approach: your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have.
+
+## Install
+
+```bash
+npx @cometchat/skills add
+```
+
+Supported IDEs: Claude Code (default), Cursor, Kiro, VS Code Copilot. Use `--ide <name>` to target a specific one, or `--ide all`.
+
+Then in your IDE:
+
+```
+/cometchat add chat to my app
+```
+
+## What happens
+
+1. **Detects** your framework (React / Next.js / React Router / Astro), router, env prefix, existing auth system
+2. **Onboards** you to CometChat in the terminal — no browser round-trip. Signup, login, app creation all via the CLI.
+3. **Asks** what you're building (marketplace, SaaS, messaging, support, social, or just exploring) and **where** chat should live in your project — it reads your routes, nav, and components before proposing a placement
+4. **Shows the plan** — exactly which files it will create, which it will modify, and which it will not touch — and waits for your approval
+5. **Writes** the provider, integration components, and route/trigger wiring
+6. **Saves** `.env` with the correct framework prefix (`VITE_` / `NEXT_PUBLIC_` / `PUBLIC_`) and records your choices in `.cometchat/config.json`
+
+No templates, no experiences to pick — the agent writes real code that fits your app.
+
+## Supported frameworks
+
+| Framework | Status |
+|---|---|
+| React.js / Vite / CRA | ✅ |
+| Next.js (App Router + Pages Router) | ✅ |
+| React Router v6 / v7 | ✅ |
+| Astro (React islands) | ✅ |
+| React Native | 🔜 Coming soon |
+| Flutter | 🔜 Coming soon |
+| Android / iOS | 🔜 Coming soon |
+
+## After the first integration
+
+Re-run `/cometchat` anytime to pick from the iteration menu:
+
+- **Customize look & feel** — theme presets (slack / whatsapp / imessage / discord / notion) or your own brand color
+- **Add a feature** — 40+ features including calls, reactions, polls, AI smart replies, file sharing, presence
+- **Customize a component** — custom message bubbles, headers, composer actions, empty/loading states
+- **Add a floating widget** — overlay chat button + drawer on top of your existing app
+- **Set up production auth** — replace the dev Auth Key with a server-side token endpoint
+- **Set up user management** — server endpoints for creating/updating/deleting CometChat users
+- **Run diagnostics** — verify, drift detection, symptom-to-cause lookup
+
+## Recommended: CometChat Docs MCP
+
+For deeper component customization (custom views, SDK events, request builders), install the docs MCP:
+
+**Claude Code:**
+```bash
+claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{ "mcpServers": { "cometchat-docs": { "url": "https://www.cometchat.com/docs/mcp" } } }
+```
+
+**Windsurf:**
+```json
+{ "mcpServers": { "cometchat-docs": { "type": "sse", "serverUrl": "https://www.cometchat.com/docs/mcp" } } }
+```
+
+No authentication required. Not needed for the initial integration — the skill handles Phase A without it.
+
+## CLI (used by the agent under the hood)
+
+The skill calls `@cometchat/skills-cli` commands. You can also run them directly:
+
+```bash
+# Onboarding
+npx @cometchat/skills-cli auth signup       # create account, all in terminal
+npx @cometchat/skills-cli auth login        # sign in (masked password)
+npx @cometchat/skills-cli auth status       # check current session
+
+# App provisioning
+npx @cometchat/skills-cli provision list    # list apps on your account
+npx @cometchat/skills-cli provision setup \
+  --name my-chat --region us --industry saas_businesses \
+  --framework reactjs                       # create app + write .env + save config
+
+# Project introspection
+npx @cometchat/skills-cli detect            # framework, router, env prefix
+npx @cometchat/skills-cli config show       # read .cometchat/config.json
+npx @cometchat/skills-cli doctor            # diagnostics
+
+# See everything
+npx @cometchat/skills-cli --help
+```
+
+## Prerequisites
+
+- An AI coding agent ([Claude Code](https://claude.ai/code), [Cursor](https://cursor.sh), [Kiro](https://kiro.dev), VS Code Copilot, or any [skills.sh](https://skills.sh)-compatible agent)
+- Node.js 18+
+- React 18+ (React 19 fully supported)
+
+No CometChat account required before starting — the skill walks you through signup from the terminal.
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// ── Lazy-load optional deps ───────────────────────────────────────────────────
+function tryRequire(name) {
+  try { return require(name); } catch { return null; }
+}
+
+const chalk = tryRequire("chalk");
+const ora = tryRequire("ora");
+
+const c = {
+  bold:   (s) => chalk ? chalk.bold(s)   : s,
+  cyan:   (s) => chalk ? chalk.cyan(s)   : s,
+  green:  (s) => chalk ? chalk.green(s)  : s,
+  yellow: (s) => chalk ? chalk.yellow(s) : s,
+  gray:   (s) => chalk ? chalk.gray(s)   : s,
+  red:    (s) => chalk ? chalk.red(s)    : s,
+  dim:    (s) => chalk ? chalk.dim(s)    : s,
+};
+
+// ── Skills registry ───────────────────────────────────────────────────────────
+const SKILLS_SRC_DIR = path.join(__dirname, "..", "skills");
+
+const SKILLS = [
+  // Core (always installed)
+  { name: "cometchat",              description: "Entry point — detects framework, handles onboarding, guides integration" },
+  { name: "cometchat-core",         description: "Foundational rules — init, login, CSS, env vars, SSR safety, provider" },
+  { name: "cometchat-components",   description: "Component catalog — names, props, composition patterns" },
+  { name: "cometchat-placement",    description: "Where to put chat — route, modal, drawer, widget, embedded" },
+  // Framework patterns
+  { name: "cometchat-react-patterns",        description: "React / Vite / CRA integration patterns" },
+  { name: "cometchat-nextjs-patterns",       description: "Next.js App Router + Pages Router patterns" },
+  { name: "cometchat-react-router-patterns", description: "React Router v6 / v7 patterns" },
+  { name: "cometchat-astro-patterns",        description: "Astro React islands patterns" },
+  // Phase B
+  { name: "cometchat-theming",         description: "Theme presets, brand colors, CSS variable overrides" },
+  { name: "cometchat-features",        description: "40+ feature catalog — calls, polls, AI, moderation" },
+  { name: "cometchat-customization",   description: "Component customization — custom views, builders, events" },
+  { name: "cometchat-production",      description: "Production auth — token endpoints, user management, security" },
+  { name: "cometchat-troubleshooting", description: "Diagnostics — verify, drift, doctor, symptom lookup" },
+];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+// ── IDE target directories ────────────────────────────────────────────────────
+const IDE_TARGETS = {
+  claude:      { local: ".claude/skills",  global: path.join(os.homedir(), ".claude", "skills"),  skillFile: "SKILL.md" },
+  // Cursor loads agent "skills" from `.cursor/skills/` (not `.cursor/rules/`).
+  cursor:      { local: ".cursor/skills",  global: path.join(os.homedir(), ".cursor", "skills"),  skillFile: "SKILL.md" },
+  kiro:        { local: ".kiro/skills",     global: path.join(os.homedir(), ".kiro", "skills"),    skillFile: "SKILL.md" },
+  copilot:     { local: ".github",          global: null,                                          skillFile: null },  // single-file mode
+};
+
+// Each skill is installed as <base>/<name>/SKILL.md (or concatenated for copilot)
+// Returns the destination path on success, or null if the source SKILL.md
+// doesn't exist.
+function installSkill(skill, baseDir, skillFile) {
+  const src = path.join(SKILLS_SRC_DIR, skill.name, "SKILL.md");
+  if (!fs.existsSync(src)) {
+    return null;
+  }
+  const skillDir = path.join(baseDir, skill.name);
+  ensureDir(skillDir);
+  const dest = path.join(skillDir, skillFile);
+  fs.copyFileSync(src, dest);
+
+  // Copy supporting files (e.g. references/component-catalog.md)
+  // that live alongside SKILL.md in the skill's directory.
+  const refsDir = path.join(SKILLS_SRC_DIR, skill.name, "references");
+  if (fs.existsSync(refsDir)) {
+    const destRefs = path.join(skillDir, "references");
+    ensureDir(destRefs);
+    for (const file of fs.readdirSync(refsDir)) {
+      fs.copyFileSync(path.join(refsDir, file), path.join(destRefs, file));
+    }
+  }
+
+  return dest;
+}
+
+function installCopilotSkills(baseDir) {
+  ensureDir(baseDir);
+  const dest = path.join(baseDir, "copilot-instructions.md");
+  let content = "# CometChat Skills\n\n";
+  for (const skill of SKILLS) {
+    const src = path.join(SKILLS_SRC_DIR, skill.name, "SKILL.md");
+    if (!fs.existsSync(src)) {
+      continue; // skip skills that haven't been promoted yet
+    }
+    content += fs.readFileSync(src, "utf8") + "\n\n---\n\n";
+  }
+  fs.writeFileSync(dest, content, "utf8");
+  return dest;
+}
+
+function printHelp() {
+  console.log(`
+  ${c.bold("cometchat-skills")} — Install CometChat AI coding skills
+
+  ${c.bold("Usage:")}
+    ${c.cyan("npx @cometchat/skills add")}                    Install for Claude Code (default)
+    ${c.cyan("npx @cometchat/skills add --ide cursor")}       Install for Cursor
+    ${c.cyan("npx @cometchat/skills add --ide kiro")}         Install for Kiro
+    ${c.cyan("npx @cometchat/skills add --ide copilot")}      Install for VS Code Copilot
+    ${c.cyan("npx @cometchat/skills add --ide all")}          Install for all supported IDEs
+    ${c.cyan("npx @cometchat/skills add --global")}           Install globally
+    ${c.cyan("npx @cometchat/skills add --list")}             Show available skills
+
+  ${c.bold("Supported IDEs:")} claude, cursor, kiro, copilot, all
+
+  ${c.bold("After installing, open your project in your IDE and run:")}
+    ${c.cyan("/cometchat")}
+`);
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (cmd !== "add") {
+    console.error(c.red(`\n  Unknown command: ${cmd}`));
+    printHelp();
+    process.exit(1);
+  }
+
+  const isGlobal = args.includes("--global") || args.includes("-g");
+  const listOnly = args.includes("--list") || args.includes("-l");
+  const ideIdx = args.indexOf("--ide");
+  const ideArg = ideIdx !== -1 ? args[ideIdx + 1] : "claude";
+
+  if (listOnly) {
+    console.log(`\n  ${c.bold("Available skills:")}\n`);
+    for (const s of SKILLS) {
+      console.log(`  ${c.cyan(s.name)}`);
+      console.log(`    ${c.dim(s.description)}\n`);
+    }
+    process.exit(0);
+  }
+
+  const targets = ideArg === "all" ? Object.keys(IDE_TARGETS) : [ideArg];
+
+  for (const ide of targets) {
+    const target = IDE_TARGETS[ide];
+    if (!target) {
+      console.error(c.red(`\n  Unknown IDE: ${ide}. Valid: ${Object.keys(IDE_TARGETS).join(", ")}, all`));
+      process.exit(1);
+    }
+
+    if (isGlobal && !target.global) {
+      console.log(`\n  ${c.yellow("⚠")} ${ide} does not support global install — skipping.`);
+      continue;
+    }
+
+    const baseDir = isGlobal ? target.global : path.join(process.cwd(), target.local);
+    const scopeLabel = isGlobal
+      ? `global  ${c.gray(`(${target.global}/`)}`
+      : `local   ${c.gray(`(${target.local}/)`)}`;
+
+    console.log(`\n  ${c.bold(c.cyan("CometChat Skills"))}  —  ${ide} integration\n`);
+    console.log(`  Scope: ${scopeLabel}\n`);
+
+    ensureDir(baseDir);
+
+    if (ide === "copilot") {
+      const spinner = ora ? ora({ text: "copilot-instructions.md", prefixText: "  " }).start() : null;
+      try {
+        const dest = installCopilotSkills(baseDir);
+        if (spinner) spinner.succeed(c.green("✓ ") + c.bold("copilot-instructions.md") + `  ${c.dim("All skills concatenated")}`);
+        else console.log(`  ✓ copilot-instructions.md`);
+      } catch (err) {
+        if (spinner) spinner.fail(c.red(`✗ copilot-instructions.md: ${err.message}`));
+        else console.error(`  ✗ copilot-instructions.md: ${err.message}`);
+      }
+    } else {
+      for (const skill of SKILLS) {
+        const spinner = ora ? ora({ text: skill.name, prefixText: "  " }).start() : null;
+        try {
+          installSkill(skill, baseDir, target.skillFile);
+          if (spinner) spinner.succeed(c.green("✓ ") + c.bold(skill.name) + `  ${c.dim(skill.description)}`);
+          else console.log(`  ✓ ${skill.name}`);
+        } catch (err) {
+          if (spinner) spinner.fail(c.red(`✗ ${skill.name}: ${err.message}`));
+          else console.error(`  ✗ ${skill.name}: ${err.message}`);
+        }
+      }
+    }
+  }
+
+  console.log(`\n  ${c.bold("Done.")} Open your project in your IDE and run:\n`);
+  console.log(`    ${c.cyan("/cometchat")}\n`);
+}
+
+main().catch((err) => {
+  console.error(chalk ? chalk.red(`\n  Error: ${err.message}`) : `\n  Error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@cometchat/skills",
+  "version": "3.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "AI coding skills for CometChat UI Kit — works with Claude Code, Cursor, Kiro, and Copilot",
+  "keywords": [
+    "claude-code",
+    "claude-skill",
+    "cometchat",
+    "react",
+    "nextjs",
+    "react-router",
+    "astro",
+    "chat",
+    "ui-kit"
+  ],
+  "author": "swapnil-cometchat",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cometchat/cometchat-skills.git"
+  },
+  "homepage": "https://github.com/cometchat/cometchat-skills#readme",
+  "bugs": {
+    "url": "https://github.com/cometchat/cometchat-skills/issues"
+  },
+  "bin": {
+    "cometchat-skills": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "setup": "node bin/install.js add",
+    "test": "bash test-suite/scripts/run-matrix.sh --models claude-sonnet-4-6 --experiences 1 --projects fresh --ide cli",
+    "test:quick": "bash test-suite/scripts/run-test.sh --framework reactjs --experience 1 --model claude-sonnet-4-6 --project fresh --keep",
+    "test:matrix": "bash test-suite/scripts/run-matrix.sh",
+    "test:trials": "bash test-suite/scripts/run-test.sh --framework reactjs --experience 1 --model claude-sonnet-4-6 --project fresh --trials 3",
+    "test:baseline": "bash test-suite/scripts/baseline.sh --framework reactjs --experience 1 --model claude-sonnet-4-6 --project fresh",
+    "test:prompts": "node test-suite/scripts/run-prompts.js --category all --model claude-sonnet-4-6",
+    "test:prompts:negative": "node test-suite/scripts/run-prompts.js --category negative --model claude-sonnet-4-6",
+    "test:prompts:edge": "node test-suite/scripts/run-prompts.js --category edge_cases --model claude-sonnet-4-6",
+    "test:prompts:dry": "node test-suite/scripts/run-prompts.js --category all --dry-run",
+    "test:gemini": "bash test-suite/scripts/run-matrix.sh --models gemini-2.5-pro,gemini-2.5-flash --provider custom --cli-cmd node --cli-flags \"$PWD/test-suite/scripts/gemini-cli.js\"",
+    "test:gemini:quick": "bash test-suite/scripts/run-test.sh --framework reactjs --experience 1 --model gemini-2.5-pro --project fresh --provider custom --cli-cmd node --cli-flags \"$PWD/test-suite/scripts/gemini-cli.js\"",
+    "test:codex": "bash test-suite/scripts/run-matrix.sh --models o3,o4-mini,gpt-4.1 --provider custom --cli-cmd node --cli-flags \"$PWD/test-suite/scripts/codex-cli.js\"",
+    "test:codex:quick": "bash test-suite/scripts/run-test.sh --framework reactjs --experience 1 --model o3 --project fresh --provider custom --cli-cmd node --cli-flags \"$PWD/test-suite/scripts/codex-cli.js\"",
+    "test:codex:matrix": "bash test-suite/scripts/run-matrix.sh --models o3,o4-mini,gpt-4.1,gpt-4.1-mini --provider custom --cli-cmd node --cli-flags \"$PWD/test-suite/scripts/codex-cli.js\"",
+    "test:report": "bash test-suite/scripts/report.sh",
+    "test:verify": "bash test-suite/scripts/verify.sh",
+    "test:eval": "bash test-suite/run.sh"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "ora": "^5.4.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.59.0",
+    "playwright": "^1.59.0",
+    "ts-morph": "^27.0.2",
+    "@google/genai": "^1.47.0",
+    "openai": "^4.80.0"
+  }
+}

package/skills/.claude-plugin/marketplace.json

@@ -0,0 +1,86 @@
+{
+  "name": "cometchat-skills",
+  "display_name": "CometChat Skills for Claude",
+  "description": "AI-native skill suite for integrating CometChat React UI Kit v6 into any React project. Skills teach Claude integration patterns, component APIs, and production hardening instead of relying on templates.",
+  "version": "3.0.0",
+  "skills": [
+    {
+      "name": "cometchat",
+      "path": "skills/cometchat/SKILL.md",
+      "group": "core",
+      "description": "Entry-point dispatcher. Detects framework, understands the project, recommends integration shape, and routes to the right skills."
+    },
+    {
+      "name": "cometchat-core",
+      "path": "skills/cometchat-core/SKILL.md",
+      "group": "core",
+      "description": "Foundational rules — initialization, login, CSS, env vars, SSR safety, provider pattern, and anti-patterns."
+    },
+    {
+      "name": "cometchat-components",
+      "path": "skills/cometchat-components/SKILL.md",
+      "group": "core",
+      "description": "Complete catalog of CometChat React UI Kit v6 components — names, props, and composition patterns."
+    },
+    {
+      "name": "cometchat-placement",
+      "path": "skills/cometchat-placement/SKILL.md",
+      "group": "core",
+      "description": "Where to put chat — route, modal, drawer, embedded panel, or floating widget patterns."
+    },
+    {
+      "name": "cometchat-react-patterns",
+      "path": "skills/cometchat-react-patterns/SKILL.md",
+      "group": "framework",
+      "description": "Integration patterns for React projects (Vite or CRA) — provider setup, routing, env vars."
+    },
+    {
+      "name": "cometchat-nextjs-patterns",
+      "path": "skills/cometchat-nextjs-patterns/SKILL.md",
+      "group": "framework",
+      "description": "Integration patterns for Next.js (App Router + Pages Router) — SSR prevention, dynamic imports, API routes."
+    },
+    {
+      "name": "cometchat-react-router-patterns",
+      "path": "skills/cometchat-react-router-patterns/SKILL.md",
+      "group": "framework",
+      "description": "Integration patterns for React Router (v6 library + v7 framework mode) — outlet nesting, SSR guards."
+    },
+    {
+      "name": "cometchat-astro-patterns",
+      "path": "skills/cometchat-astro-patterns/SKILL.md",
+      "group": "framework",
+      "description": "Integration patterns for Astro — React islands, client:only rendering, island communication."
+    },
+    {
+      "name": "cometchat-theming",
+      "path": "skills/cometchat-theming/SKILL.md",
+      "group": "features",
+      "description": "Theme customization — CSS variable overrides, preset themes, dark mode, brand color mapping."
+    },
+    {
+      "name": "cometchat-features",
+      "path": "skills/cometchat-features/SKILL.md",
+      "group": "features",
+      "description": "Feature catalog — calls, reactions, polls, AI features, and how to enable each one."
+    },
+    {
+      "name": "cometchat-production",
+      "path": "skills/cometchat-production/SKILL.md",
+      "group": "features",
+      "description": "Production readiness — server-side token auth, user management CRUD, environment hardening, security checklist."
+    },
+    {
+      "name": "cometchat-customization",
+      "path": "skills/cometchat-customization/SKILL.md",
+      "group": "features",
+      "description": "Component customization — four-tier discovery, custom view slots, request builders, event subscriptions, and CSS overrides."
+    },
+    {
+      "name": "cometchat-troubleshooting",
+      "path": "skills/cometchat-troubleshooting/SKILL.md",
+      "group": "features",
+      "description": "Diagnostics — verify checks, drift detection, error decoding, and targeted fixes."
+    }
+  ]
+}