cometchat-customization

Imported from cometchat/cometchat-skills (skills/cometchat-customization/SKILL.md). Install upstream with npx skills add cometchat/cometchat-skills --skill cometchat-customization. Copyright stays with the author (MIT).

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).
2. Prefer composition (custom view props) over CSS overrides when both are options — composition is more stable across SDK versions.
3. 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 · Call Log Details · Group Management · Message Privately · New Chat · Search Messages · 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

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:

   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:

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":

⚠️ 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:

   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:

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

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:

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:

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

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:

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:

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

npx @cometchat/skills-cli verify --json

The 5 AST checks still apply to customized files. If anything fails, surface verbatim and offer to revert.

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.