@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-customization/SKILL.md

@@ -1,580 +0,0 @@
----
-name: cometchat-customization
-description: Customize a CometChat React UI Kit integration beyond what `cometchat init` and `cometchat apply-feature` produce — custom message bubbles, custom header views, custom subtitle views, custom empty/loading states, custom action menus, request builder filters, event listeners, and component composition. Picks up where the framework skills end (after Phase A init succeeds).
-license: "MIT"
-compatibility: "Node.js >=18; @cometchat/chat-uikit-react ^6"
-metadata:
-  author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat react customization custom-view message-bubble header-view subtitle-view request-builder events"
----
-
-> **Ground truth:** the per-platform UI Kit customization systems (theme objects / CSS vars, message templates, text formatters) verified against the installed kit. (Official docs linked below.) Verify symbols against the installed package/source before relying on them.
-
-> **Companion skills:** `cometchat-components` provides the component
-> catalog (what exists); this skill provides the customization workflow
-> (how to modify what exists). Use `cometchat-components` to look up
-> component names and props, then use this skill to plan and execute
-> the customization. For any pattern not covered below, the docs MCP
-> at `cometchat-docs` is the source of truth — query it before
-> generating any code.
-
-## Use this skill when
-
-The user has already run `/cometchat` (or invoked the cometchat skill via their agent's mechanism — keyword "cometchat" or "integrate chat" works in most agents) (Phase A complete — there's a
-working integration with `.cometchat/state.json`) and wants to **change
-how a component looks or behaves** beyond what the CLI's deterministic
-commands handle.
-
-Trigger phrases:
-- "customize the message list"
-- "filter the conversations to only show X"
-- "change the message bubble color/shape/layout"
-- "add a custom header above the chat"
-- "subscribe to message-received events"
-- "show a custom loading state"
-- "add a custom action to the message options menu"
-- "I want to inject my own UI into CometChatX"
-- `/cometchat customize`
-
-## Do not use this skill when
-
-- The user wants to enable a **packaged feature** (calls, polls, AI smart
-  replies, etc.) → use `cometchat-features` instead
-- The user wants to change **theme tokens** (primary color, font,
-  border radius) → use `cometchat-theming` instead (CSS-variable
-  overrides written directly into the project — there is no theming CLI)
-- The user wants to **start a new integration** → use the `cometchat`
-  dispatcher skill to run Phase A first
-- The user wants to **fix something broken** → use
-  `cometchat-troubleshooting` and run `cometchat doctor`
-
-## Docs MCP contract
-
-This skill is **fundamentally docs-driven** — every customization
-question requires a fact (prop name, callback signature, builder method,
-event topic, CSS selector) that lives in the canonical CometChat docs,
-not in this skill's text. Embedding examples here would create drift
-the moment the SDK changes.
-
-The canonical CometChat docs are the source of truth for this skill. The
-docs MCP at `cometchat-docs` is the **best** way to query them when
-available, but it is **not** a hard requirement — fall back to the public
-docs site for any agent without it. The docs cover:
-
-- Component prop tables (every component, every prop, every default)
-- Custom view slots: `headerView`, `subtitleView`, `tailView`,
-  `optionsView`, `bubbleView`, `emptyView`, `loadingView`, `errorView`
-  (which components support which slots — verified against the v6 React
-  kit: the list components `CometChatConversations`/`MessageList`/`Users`/
-  `Groups` use `emptyView`/`loadingView`/`errorView`, **not** the
-  `*StateView` form; only `CometChatNotificationFeed` uses
-  `emptyStateView`/`loadingStateView`/`errorStateView`)
-- Message template overrides (`CometChatMessageTemplate.type`,
-  `category`, `contentView`, `headerView`, `footerView`)
-- Request builders for filtering data: `ConversationsRequestBuilder`,
-  `MessagesRequestBuilder`, `UsersRequestBuilder`, `GroupsRequestBuilder`,
-  `CallLogsRequestBuilder` and their methods
-- SDK events: `CometChatMessageEvents`, `CometChatUserEvents`,
-  `CometChatGroupEvents`, `CometChatCallEvents`, `CometChatUIEvents`
-  and the topic names
-- CSS selectors for component-level styling overrides
-  (`.cometchat-message-bubble-incoming`, `.cometchat-conversations-header`,
-  etc.)
-
-**Hard rules:**
-
-1. **Look up the docs before generating any customization code.** Never
-   invent prop names, builder methods, event topics, or CSS classes from
-   training-data memory. Use whichever lookup path is available, in order:
-   - **(a) docs MCP** — query the `cometchat-docs` MCP tool if your agent
-     has it. Richest path.
-   - **(b) install the MCP, if your agent supports it** — Claude Code:
-     `claude mcp add --transport http cometchat-docs
-     https://www.cometchat.com/docs/mcp`. Other agents (Cursor, Codex,
-     Cline, …) configure MCP their own way, or not at all — do NOT block.
-   - **(c) fetch/search the public docs** — same content at the canonical
-     URLs below, or web-search `site:cometchat.com/docs`. Universal
-     fallback; never STOP and dead-end the user when the MCP isn't
-     installed — fall through to (c).
-3. **Prefer composition (custom view props) over CSS overrides** when
-   both are options — composition is more stable across SDK versions.
-4. **Canonical reference URLs:**
-   - Components overview: https://www.cometchat.com/docs/ui-kit/react/components-overview
-   - Guides index: https://www.cometchat.com/docs/ui-kit/react/guide-overview — the 7 maintained task recipes (prefer these over hand-rolling): [Block/Unblock](https://www.cometchat.com/docs/ui-kit/react/guide-block-unblock-user) · [Call Log Details](https://www.cometchat.com/docs/ui-kit/react/guide-call-log-details) · [Group Management](https://www.cometchat.com/docs/ui-kit/react/guide-group-chat) · [Message Privately](https://www.cometchat.com/docs/ui-kit/react/guide-message-privately) · [New Chat](https://www.cometchat.com/docs/ui-kit/react/guide-new-chat) · [Search Messages](https://www.cometchat.com/docs/ui-kit/react/guide-search-messages) · [Threaded Messages](https://www.cometchat.com/docs/ui-kit/react/guide-threaded-messages)
-   - **Custom message recipes** (verified, copy-ready): custom message TYPES, overriding an existing type's bubble (`bubbleView`/`contentView`), adding a Message Composer attachment option, and adding a message action like Forward — all live in **`cometchat-features` §Type 5** (append-not-replace via `CometChatUIKit.getDataSource()`). Route there for the actual code; this skill covers the custom-VIEW-slot props.
-   - Theming + styling: https://www.cometchat.com/docs/ui-kit/react/theme
-   - Events: https://www.cometchat.com/docs/ui-kit/react/events
-   - Methods: https://www.cometchat.com/docs/ui-kit/react/methods
-   - **Text formatters** (inline mention/URL/markdown/custom-token styling — `CometChatTextFormatter`): the four formatter guides `custom-text-formatter-guide`, `mentions-formatter-guide`, `url-formatter-guide`, `shortcut-formatter-guide` under `ui-kit/react/`. Recipe + the append-not-replace `getAllTextFormatters({})` pattern live in **`cometchat-features` §Type 5 → Text formatters**.
-   - **Localization** (languages, custom strings, date/time formatting): handled by the dedicated **`cometchat-i18n`** skill (`CometChatLocalize`) — route there for any locale/string work; docs https://www.cometchat.com/docs/ui-kit/react/localize
-
-## Steps
-
-### Step 1 — Verify Phase A is done
-
-```bash
-npx @cometchat/skills-cli info --json
-```
-
-If `integrated` is `false`, **stop** and tell the user to run
-`/cometchat` first to create the base integration. Customization
-modifies an existing integration; it doesn't create one.
-
-Note the `framework`, `experience`, `files_owned`, and `applied_features`
-from the response — you'll need them in the next steps.
-
-### Step 2 — Four-tier discovery: existing-component prop, new component, stylesheet, sample app
-
-> **START HERE:** Read the **component catalog** at
-> `references/component-catalog.md` (in this skill's directory). It has
-> the canonical list of all 88 exported symbols, all 14 sample-app
-> patterns, and a 40-row task→component lookup table. If the user's
-> request maps to an entry in the catalog, use that entry directly —
-> skip the rest of this step.
-
-**If the catalog doesn't have a match (or you need prop-level detail),
-walk these FOUR discovery checks in this exact order:**
-
-1. **Existing-component prop check (2a):** does a component the
-   integration ALREADY mounts have a prop that does what the user is
-   asking for? **The kit follows a "props over components" philosophy
-   — most additions are props on existing components, not new
-   components.** This check goes FIRST.
-2. **New-component check (2b):** if 2a turned up nothing, is there a
-   built-in `CometChat<X>` component in `@cometchat/chat-uikit-react`'s
-   exports?
-3. **Stylesheet check (2c):** is there a `--cometchat-<x>` CSS
-   variable for any styling you'd write?
-4. **Sample app check (2d):** is there a reference implementation in
-   the sample app at
-   `github.com/cometchat/cometchat-uikit-react/tree/v6/sample-app/src/components`
-   for the user's pattern?
-
-The CometChat React UI Kit ships FOUR things, not one:
-- A "props over components" API where most features (search bar,
-  filters, custom views, click handlers, disable flags) are PROPS on
-  existing components — NOT new components
-- 60+ named React components in the npm package
-- A 200+ CSS variable system at
-  `@cometchat/chat-uikit-react/css-variables.css`
-- A reference sample app on GitHub with implementations for common
-  chat UX patterns (user/group details, threaded messages layout,
-  top-level home layout, multi-tab chat, notifications, new chat
-  dialog, etc.) that combine multiple kit components but aren't
-  shipped as single named exports
-
-**Critical:** the docs MCP does NOT index the sample app. When the MCP
-says *"no `CometChat<X>` component exists"*, that only covers the npm
-package — you must still check the sample app via GitHub before
-concluding the user needs hand-rolled code.
-
-Hand-rolling something the kit, the variable system, OR the sample
-app already provides means missing the kit's theming, accessibility,
-i18n, error handling, and every future SDK update.
-
-#### 2a. Existing-component prop check (do this FIRST)
-
-**Most chat features are already props on the components you have.**
-A user asking for "add search", "filter conversations", "custom empty
-state", or "click handler on a message" is almost always asking for a
-prop, not a new component or custom code.
-
-**Process:**
-
-1. **List the CometChat components currently mounted in the
-   integration.** Read the integration's owned files (from
-   `state.json`) and grep for `<CometChat` JSX usage:
-   ```bash
-   grep -hoE '<CometChat[A-Z][a-zA-Z]*' \
-     $(jq -r '.files_owned[]' .cometchat/state.json 2>/dev/null) \
-     2>/dev/null | sort -u
-   ```
-2. **Query the docs MCP for the props of each mounted component:**
-   - `"CometChatConversations props"`
-   - `"CometChatMessageList props"`
-   - `"CometChatMessageHeader props"`
-   - `"CometChatMessageComposer props"`
-3. **Look for a prop that maps to the user's intent.** Common
-   mappings:
-
-| User asks for | Likely prop on which component |
-|---|---|
-| Search bar / "add search" | `showSearchBar` on `CometChatConversations` (or `onSearchBarClicked` to swap in `<CometChatSearch>` for advanced dual-scope search) |
-| Filter conversations | `conversationsRequestBuilder` on `CometChatConversations` |
-| Filter messages | `messagesRequestBuilder` on `CometChatMessageList` |
-| Filter users / groups | `usersRequestBuilder` / `groupsRequestBuilder` |
-| Custom empty state | `emptyView` on the list components (`Conversations`/`MessageList`/`Users`/`Groups`); `emptyStateView` only on `CometChatNotificationFeed` |
-| Custom error UI | `errorView` (list components); `errorStateView` on `CometChatNotificationFeed` |
-| Custom loading UI | `loadingView` (list components); `loadingStateView` on `CometChatNotificationFeed` |
-| Custom header above the list | `headerView` |
-| Custom message bubble | `templates` prop on `CometChatMessageList` (not a custom bubble component) |
-| Click handler on item / message / search bar / back button | `onItemClick`, `onMessageClick`, `onBack`, `onSearchBarClicked` |
-| Hide / disable a sub-feature | `disable*` boolean props (e.g. `disableTyping`, `disableReactions`) |
-| Custom subtitle / status / timestamp | `subtitleView`, `statusView`, `timestampView` |
-| Show / hide receipts | `hideReceipts` |
-| Selection mode | `selectionMode` on list components |
-
-If you find a matching prop, **just add the prop and stop**. No new
-components. No custom CSS. No new files. Surface to the user: *"The
-`<X>` you already have supports this via the `<propName>` prop. Adding
-that single prop."*
-
-If 2a turns up nothing, proceed to 2b.
-
-#### 2b. New-component check (do this only if 2a turned up nothing)
-
-**Common requests that look like "customization" but are actually
-"use the existing component":**
-
-| User asks for | Use this built-in component |
-|---|---|
-| Threaded replies / "wire up threads" | `CometChatThreadHeader` + scope a `CometChatMessageList` and `CometChatMessageComposer` with `parentMessageId` |
-| Group members panel / "list group members" | `CometChatGroupMembers` |
-| Add members to a group | `CometChatAddMembers` |
-| Transfer group ownership | `CometChatTransferOwnership` |
-| Banned users management | `CometChatBannedMembers` |
-| Block/unblock users panel | `CometChatBlockedUsers` |
-| New chat / "start a new conversation" dialog | `CometChatNewChat` |
-| Create new group dialog | `CometChatCreateGroup` |
-| User / group details panel | `CometChatDetails` |
-| Mentions popover in composer | `CometChatMentionsFormatter` (already wired into the composer) |
-| Voice / video call buttons in header | `CometChatCallButtons` |
-| Outgoing call screen | `CometChatOutgoingCall` |
-| Incoming call notification | `CometChatIncomingCall` |
-| Ongoing call UI | `CometChatOngoingCall` |
-| Call logs list | `CometChatCallLogs` |
-| Reactions on messages | Already built into `CometChatMessageList` — check if it's just disabled |
-| Message bubble customization | Use the `templates` prop on `CometChatMessageList`, not a custom bubble component |
-
-> ⚠️ **Not every row above is a kit export.** `CometChatAddMembers`, `CometChatTransferOwnership`, `CometChatBannedMembers`, `CometChatBlockedUsers`, `CometChatNewChat`, `CometChatCreateGroup`, and `CometChatDetails` are **sample-app components, NOT `@cometchat/chat-uikit-react` v6 exports** — importing `<CometChatTransferOwnership/>` etc. is an unresolved-import build error. Build these by copying the sample-app implementation (§2d), do not import them from the package. The genuinely package-exported entries in this table are: `CometChatThreadHeader`, `CometChatGroupMembers`, `CometChatMentionsFormatter`, `CometChatCallButtons`, `CometChatOutgoingCall`, `CometChatIncomingCall`, `CometChatOngoingCall`, `CometChatCallLogs`. **Always grep the installed package's exports (next step) before emitting any of these.**
-
-**Search strategies, in this order:**
-
-1. **Query the docs MCP** with the user's intent in plain English.
-   Examples:
-   - `"thread reply UI react ui kit"` → finds `CometChatThreadHeader`
-   - `"new chat dialog"` → finds `CometChatNewChat`
-   - `"group transfer ownership"` → finds `CometChatTransferOwnership`
-   - `"block user list"` → finds `CometChatBlockedUsers`
-2. **Grep the user's installed package** for matching exports:
-   ```bash
-   grep -E "^export.*CometChat[A-Z][a-zA-Z]+" \
-     node_modules/@cometchat/chat-uikit-react/dist/index.d.ts \
-     2>/dev/null | head -50
-   ```
-3. **Browse the v6 components reference** at
-   https://www.cometchat.com/docs/ui-kit/react/components-overview
-
-If you find a built-in component that matches, **use it as-is**.
-Surface to the user: *"The kit already ships `CometChat<X>` for this.
-I'll wire it up directly."*
-
-#### 2c. Stylesheet check (do this even when you DO need custom layout glue)
-
-Even when you have to write some CSS for layout glue (positioning a
-panel, sizing a container, wiring up the height chain that
-`.cometchat-message-list` requires), **never hand-pick colors, fonts,
-borders, spacings, or radii from your head**. The kit ships a
-canonical CSS variable system. Use it.
-
-**The rule:**
-- ✅ **OK:** custom CSS for layout glue (positioning, sizing, flex
-  containers, the height chain). Example: `.thread-wrapper { width:
-  400px; height: 100vh; display: flex; flex-direction: column; }`
-- ✅ **OK:** custom CSS that consumes kit variables. Example:
-  `.thread-wrapper { border-left: 1px solid var(--cometchat-border-color-light); background: var(--cometchat-background-color-01); }`
-- ❌ **NOT OK:** custom CSS for any header / button / icon / panel /
-  badge / divider that the kit already provides as a component.
-  Example: a hand-rolled `.thread-header` + `.thread-close` button when
-  `CometChatThreadHeader` exists.
-- ❌ **NOT OK:** hardcoded colors / fonts / borders / radii / spacings
-  that don't reference the `--cometchat-*` variables. Example:
-  `border: 1px solid #E8E8E8` instead of
-  `border: 1px solid var(--cometchat-border-color-light)`.
-
-**Discovery commands for the variable system:**
-```bash
-# List every --cometchat-* variable the kit defines
-grep -oE '\-\-cometchat-[a-z0-9-]+' \
-  node_modules/@cometchat/chat-uikit-react/css-variables.css \
-  2>/dev/null | sort -u | head -60
-
-# Or search for a specific token category
-grep -E '\-\-cometchat-(border|background|text|primary|font)' \
-  node_modules/@cometchat/chat-uikit-react/css-variables.css \
-  2>/dev/null | head -40
-```
-
-**Common variable categories** (query the docs MCP for the canonical
-list — these change between SDK versions):
-
-| Category | Example variables |
-|---|---|
-| Brand colors | `--cometchat-primary-color`, `--cometchat-error-color`, `--cometchat-success-color` |
-| Backgrounds | `--cometchat-background-color-01` (white), `--cometchat-background-color-02`, `--cometchat-background-color-03` (light grey) |
-| Text | `--cometchat-text-color-primary`, `--cometchat-text-color-secondary`, `--cometchat-text-color-tertiary` |
-| Borders | `--cometchat-border-color-light`, `--cometchat-border-color-default`, `--cometchat-border-color-dark` |
-| Radii | `--cometchat-radius-1`, `--cometchat-radius-2`, `--cometchat-radius-3`, `--cometchat-radius-max` |
-| Fonts | `--cometchat-font-heading1-bold`, `--cometchat-font-heading4-medium`, `--cometchat-font-body-regular`, `--cometchat-font-caption2-regular` |
-| Spacing | `--cometchat-spacing-1` through `--cometchat-spacing-10` |
-| Shadows | `--cometchat-shadow-1`, `--cometchat-shadow-2`, `--cometchat-shadow-3` |
-
-#### 2d. Sample app reference check (do this when 2a + 2b turned up nothing)
-
-If 2b didn't find a `CometChat<X>` component for the user's request,
-**don't immediately conclude they need custom code**. The kit ships a
-**reference sample app** at:
-
-> https://github.com/cometchat/cometchat-uikit-react/tree/v6/sample-app/src/components
-
-with implementations for common chat UX patterns that combine multiple
-kit components but aren't shipped as single named exports. Examples
-that look like "missing components" but are in the sample app:
-
-| User asks for | Sample app reference path |
-|---|---|
-| User / group details panel | `sample-app/src/components/CometChatDetails/CometChatUserDetails.tsx` (group details is inline in `CometChatHome.tsx`'s `SideComponentGroup`) |
-| Threaded messages panel layout | `sample-app/src/components/CometChatDetails/CometChatThreadedMessages.tsx` |
-| Top-level chat layout (left pane + main + side rail) | `sample-app/src/components/CometChatHome/CometChatHome.tsx` |
-| Multi-tab chat (Chats / Calls / Users / Groups) | `sample-app/src/components/CometChatSelector/CometChatTabs.tsx` |
-| New conversation dialog with user/group picker | Inline in `CometChatHome.tsx` as `CometChatNewChatView` (CSS: `sample-app/src/styles/CometChatNewChat/CometChatNewChatView.css`) |
-| Search view (conversations + messages) | `sample-app/src/components/CometChatSearchView/` |
-| Call log details / history / recordings | `sample-app/src/components/CometChatCallLog/` (5 sub-files: Details, History, Info, Participants, Recordings) |
-| App state / active-chat React context | `sample-app/src/context/AppContext.jsx` + `appReducer.ts` |
-| Group ownership transfer modal | `sample-app/src/components/CometChatTransferOwnership/` |
-
-These patterns include matching CSS at
-`sample-app/src/styles/<ComponentName>/` using BEM-style class names
-that are already wired to the kit's CSS variable system.
-
-**Discovery commands:**
-
-```bash
-# List the sample app's components directory via the GitHub API
-curl -s "https://api.github.com/repos/cometchat/cometchat-uikit-react/contents/sample-app/src/components?ref=v6" \
-  | grep -oE '"name":\s*"[^"]+"' | head -30
-
-# Fetch a specific component file directly
-curl -s "https://raw.githubusercontent.com/cometchat/cometchat-uikit-react/v6/sample-app/src/components/CometChatDetails/CometChatUserDetails.tsx"
-
-# Fetch its matching stylesheet
-curl -s "https://raw.githubusercontent.com/cometchat/cometchat-uikit-react/v6/sample-app/src/styles/CometChatDetails/CometChatUserDetails.css"
-```
-
-You can also use WebFetch on the URLs above. The docs MCP does NOT
-index the sample app — you must fetch it from GitHub directly.
-
-**If you find a matching reference implementation:**
-
-1. Read BOTH the `.tsx` file AND its matching `.css` file (at
-   `sample-app/src/styles/<ComponentName>/`)
-2. Mirror the sample app's file/folder structure in the user's project,
-   e.g. `src/cometchat/CometChatDetails/CometChatUserDetails.tsx` plus
-   `src/cometchat/CometChatDetails/CometChatDetails.css`
-3. Match the **exact BEM class names** from the sample
-   (`.cometchat-user-details__header`,
-   `.cometchat-user-details__content-avatar`, etc.) — they're already
-   integrated with the kit's CSS variable system
-4. Strip the sample app's local dependencies that the user's project
-   doesn't have:
-   - `useContext(AppContext)` → inline the values
-   - `getLocalizedString(...)` → inline the English strings
-   - `cometchat-resources/` SVG icons → use Unicode equivalents or
-     strip them
-5. Tell the user: *"The kit doesn't export this as a single component,
-   but the official sample app has the reference implementation at
-   `cometchat/cometchat-uikit-react/v6/sample-app/.../CometChat<X>`.
-   I'm adapting it to your project."*
-
-#### 2e. After discovery — decide what to do
-
-In strict order, take the FIRST option that applies:
-
-1. **An existing component prop matches (2a):** add the prop. Done.
-   No new files. Most chat features land here.
-2. **A new component matches (2b) AND has its own styling:** use the
-   component as-is. Zero custom CSS.
-3. **A new component matches (2b) but you need layout glue:** use the
-   component; write minimal layout-only CSS that consumes
-   `--cometchat-*` variables (per 2c).
-4. **Sample app has a reference implementation (2d):** adapt the
-   sample app pattern, mirroring its file structure and BEM class
-   names.
-5. **None of the above:** then (and only then) proceed to Step 3 to
-   classify the request as a true customization.
-
-### Step 3 — Classify the customization
-
-Read the user's request and place it into one of these buckets. The
-right approach is different per bucket:
-
-| Bucket | Examples | Approach |
-|---|---|---|
-| **A. Custom view slot** | "add a custom header above the conversation list", "show a custom empty state", "render messages with my own bubble" | Use the corresponding `*View` prop (`headerView`, `emptyView`, `bubbleView`, etc.) — look up which prop the target component supports (list components use `emptyView`/`loadingView`/`errorView`; `CometChatNotificationFeed` uses the `*StateView` form) |
-| **B. Filter / pagination** | "only show conversations with VIP users", "load 10 messages at a time", "show only joined groups" | Use the corresponding RequestBuilder (`ConversationsRequestBuilder.setTags`, `setLimit`, `setUserAndGroupTags`, etc.) — query the MCP for the builder methods |
-| **C. Action / callback** | "do X when a user clicks a conversation", "intercept message send", "log every search" | Use the corresponding `on*` callback prop (`onItemClick`, `onSendButtonClick`, `onSearch`, etc.) — query the MCP for the callback signature |
-| **D. Event subscription** | "show a toast when a new message arrives", "update my unread count when someone reads a message", "track typing indicators" | Subscribe to the corresponding `CometChat*Events` topic (`CometChatMessageEvents.ccMessageSent`, `ccMessageRead`, `CometChatUserEvents.ccUserOnline`, etc.) — query the MCP for the event topic |
-| **E. Component-level CSS** | "make incoming bubbles green", "hide the conversation timestamps", "compact the message list spacing" | Add a CSS rule under `.cometchat <selector>` in the integration's global stylesheet — query the MCP for the right selector class. NEVER invent class names; the SDK's selectors are namespaced and prefix-protected. |
-| **F. Component composition** | "wrap CometChatConversations with my own search bar", "render two CometChatGroups side by side", "embed CometChatMessageList inside my own card layout" | Standard React composition. The CometChat components are React components — use them like any other component. Query the MCP for which props are required vs optional. |
-
-> **Message templates / options / composer attachments → use the verified recipes in `cometchat-features` §Type 5**, not a hand-rolled `bubbleView`. Sending a custom message TYPE, overriding an existing type's bubble, adding a Forward-style message action, or adding a composer attachment all require the **append-not-replace** `CometChatUIKit.getDataSource()` merge (a bare `templates=`/`attachmentOptions=` array silently wipes the built-ins — ENG-35706). §Type 5 has the copy-ready, tsc-verified code.
-
-If the user's request doesn't fit any bucket, **ask them to clarify** —
-don't guess. Customization is the place where ambiguous requests
-produce wrong code most often.
-
-### Step 4 — Query the docs MCP for the canonical pattern (only if Step 2 turned up nothing)
-
-Once you've classified the request, query the docs MCP with a specific
-search:
-
-| Bucket | MCP query example |
-|---|---|
-| A. Custom view slot | "headerView prop CometChatConversations" |
-| B. Filter / pagination | "ConversationsRequestBuilder methods setTags" |
-| C. Action / callback | "CometChatMessageList onMessageClick callback signature" |
-| D. Event subscription | "CometChatMessageEvents ccMessageSent subscribe" |
-| E. Component-level CSS | "CSS selector cometchat-message-bubble-incoming" |
-| F. Component composition | "CometChatConversations props required" |
-
-The MCP returns canonical, current docs. Read them BEFORE writing any
-code. If multiple results come back, prefer the React UI Kit v6 result
-over older versions.
-
-### Step 5 — Identify the file to modify
-
-Use the framework + experience you noted in Step 1 to find the right
-file. The integration's primary client file is conventional per
-framework:
-
-| Framework | Primary client file |
-|---|---|
-| reactjs (Vite) | `src/App.tsx` (renders the conversation list / messages) + `src/cometchat/CometChatSelector.tsx` (the selector) |
-| nextjs (App Router) | `src/app/cometchat/CometChatNoSSR.tsx` (renders the chat) + `src/app/cometchat/CometChatSelector.tsx` (the selector) |
-| nextjs (Pages Router) | `src/cometchat/CometChatNoSSR.tsx` + `src/cometchat/CometChatSelector.tsx` |
-| react-router (v6 + v7) | `app/cometchat/CometChatNoSSR.tsx` + `app/cometchat/CometChatSelector.tsx` |
-| astro | `src/cometchat/ChatApp.tsx` (the React island) + `src/cometchat/CometChatSelector.tsx` |
-
-For CSS overrides (bucket E), the global stylesheet is:
-- reactjs → `src/index.css`
-- nextjs (App Router) → `src/app/globals.css`
-- nextjs (Pages Router) → `src/styles/globals.css`
-- react-router → `app/app.css`
-- astro → inside `src/cometchat/ChatApp.tsx` (NOT a global stylesheet)
-
-These are also in `state.json` under `files_owned` if you need to verify.
-
-### Step 6 — Write the customization
-
-Generate the code based on the docs MCP response from Step 4. Show the
-user:
-
-1. **What you're going to change** (which file, which lines, the new
-   code)
-2. **Why** (which prop/builder/event the docs say to use)
-3. **A preview of the diff** (just the changed region, not the whole
-   file)
-
-**Wait for the user to confirm** before writing. Customization edits
-the integration's owned files — drift detection will show this on the
-next `cometchat info`. The user should know.
-
-If the user confirms, write the change. If they don't, surface what
-they'd want to change and stop.
-
-### Step 7 — Verify
-
-```bash
-npx @cometchat/skills-cli verify --json
-```
-
-The 5 AST checks still apply to customized files. If anything fails,
-surface verbatim and offer to revert.
-
-```bash
-npx @cometchat/skills-cli info --json
-```
-
-The customized file will now show as drifted (its checksum no longer
-matches the original template). This is expected — it's the
-**explicit** drift the user just asked for. Not a bug.
-
-### Step 8 — Tell the user what to do next
-
-The dev server picks up React changes via HMR. Tell the user:
-1. Save the file (if their editor doesn't auto-save)
-2. Refresh the browser tab
-3. Test the customization
-
-Then offer to do another customization OR to return to the framework
-skill's Phase B menu.
-
-## Hard rules
-
-- **Always do the FOUR-tier discovery before adding any new component
-  or hand-rolled UI.** The kit follows a "props over components"
-  philosophy and ships FOUR things, not one:
-  (0) **props** on already-mounted components for most features
-      (search bar, filters, custom views, click handlers, disable
-      flags) — check this FIRST,
-  (1) 60+ named React components in `@cometchat/chat-uikit-react`,
-  (2) a 200+ CSS variable system in `css-variables.css`,
-  (3) a reference sample app at
-      `github.com/cometchat/cometchat-uikit-react/tree/v6/sample-app/src/components`
-      with implementations for common chat UX patterns that combine
-      multiple kit components but aren't shipped as single named
-      exports (user/group details panels, thread layouts, top-level
-      home layout, notifications, new chat dialog, etc.).
-  The docs MCP does NOT index the sample app — fetch it from GitHub
-  directly. Adding a new component when an existing one's prop would
-  do, or hand-rolling something the kit, the variable system, or the
-  sample app already provides, means missing the kit's theming, i18n,
-  accessibility, and every future SDK update. Step 2 (subsections 2a
-  + 2b + 2c + 2d) is mandatory — do NOT skip it. **2a
-  (existing-component prop check) goes FIRST** because most features
-  are props on already-mounted components, not new components.
-- **Custom CSS is allowed ONLY for layout glue** (positioning,
-  sizing, flex/grid containers, the height chain). Even there, never
-  hardcode colors / fonts / borders / radii / spacings — always
-  reference `--cometchat-*` variables. Hand-rolled headers, buttons,
-  icons, panels, badges, dividers, etc. are NEVER OK if the kit
-  already provides them.
-- **Always query the docs MCP first** for any prop, builder, event, or
-  CSS selector. Never invent SDK API from memory.
-- **Verify Phase A is done** before customizing. This skill modifies
-  existing integration files; it does not create new ones.
-- **Show the user the change before writing**. Customization is
-  user-side intent — they need visibility.
-- **Drift detection is expected after customization**, not a bug.
-  The user's customizations live in `state.files_owned` and will
-  show up in `cometchat info` as modified. That's correct.
-- **Prefer composition over CSS overrides** when both are options —
-  composition is stable across SDK versions; CSS selectors are not.
-- **Never invent CSS class names** — look them up in the docs. The SDK's
-  class prefix is `.cometchat-` but the leaf names (`-message-bubble-incoming`,
-  `-conversations-header`, etc.) MUST come from the docs.
-- **Look up the docs via the best available path** (see §2's lookup
-  contract): docs MCP if your agent has it → else fetch/web-search the
-  public docs at cometchat.com/docs. Never STOP just because the MCP
-  isn't installed — fall through to the public docs.
-- **Always use `npx @cometchat/skills-cli`** for any CLI commands.
-
-## What this skill does NOT do
-
-- It does not write **template** files (that's `cometchat init`)
-- It does not **enable packaged features** (that's `cometchat-features`
-  + `cometchat apply-feature`)
-- It does not **change theme tokens** (that's `cometchat-theming` —
-  CSS-variable overrides, no CLI)
-- It does not **fix broken integrations** (that's
-  `cometchat-troubleshooting` + `cometchat doctor`)
-- It does not **add new components from scratch** — it customizes
-  components that the integration already uses
-
-For anything in the "does not" list, route the user to the right
-skill/command instead of attempting it here.
-
-## Sound (in-app message + call sounds)
-
-Sound is a customization sub-dimension. The UI Kit plays incoming/outgoing message + call sounds via `CometChatSoundManager` — mute it, swap custom audio, or play a specific sound. The full API + recipe lives in **`cometchat-theming`** (Sound section). Verify the access path against the installed kit before relying on it.