AGENT SKILL

cometchat-onboarding

The shared FRONT DOOR for adding CometChat to ANY app — a consultative, enterprise-grade DISCOVER → UNDERSTAND → PLAN journey that ALWAYS runs first, before any framework core. Detects the whole repo, runs a features + design-system conversation (core chat/threads/groups/media/calls/search/...; a preset theme, match your design system, or build one), maps each feature to its UI Kit component (or the SDK method where the UI Kit has none — UI-Kit-first, SDK-fallback), shares a full integration PLAN, then hands a scoped build directive to the framework core on approval — final output is production-ready. Triggers: 'add cometchat', 'add chat', 'add chat to my app', 'add calling', 'integrate cometchat', 'build a chat feature', 'build a <app> clone', 'make it like <app>'.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
cometchat-onboarding
license
MIT
metadata
{ "tags": "cometchat onboarding journey discover understand plan front-door router-gate agnostic intent", "author": "CometChat", "version": "1.0.0" }
description
The shared FRONT DOOR for adding CometChat to ANY app — a consultative, enterprise-grade DISCOVER → UNDERSTAND → PLAN journey that ALWAYS runs first, before any framework core. Detects the whole repo, runs a features + design-system conversation (core chat/threads/groups/media/calls/search/...; a preset theme, match your design system, or build one), maps each feature to its UI Kit component (or the SDK method where the UI Kit has none — UI-Kit-first, SDK-fallback), shares a full integration PLAN, then hands a scoped build directive to the framework core on approval — final output is production-ready. Triggers: 'add cometchat', 'add chat', 'add chat to my app', 'add calling', 'integrate cometchat', 'build a chat feature', 'build a <app> clone', 'make it like <app>'.
compatibility
Framework-agnostic (React/Next/Angular/Vue/RN/Flutter/Android/iOS/... — degrades gracefully when a signal is absent). Emits NO CometChat components — output is a plan artifact + a scoped directive to a framework core skill.

02 资源文件 6

03 SKILL.md 正文

Ground truth: this skill runs FIRST for every "add CometChat" request and produces NO integration code — its only outputs are (1) the shared plan artifact and (2) a scoped build directive to the framework core. Repo facts come from npx @cometchat/skills detect --json (the authority) + READING THE REPO for the rest — NEVER memory (AUDIT-059). The archetype→capability map and plan template are in references/ (loaded on demand). Credentials + implementation belong to the framework core (cometchat-<family>-core, family resolved from peers.yaml). Draw the boundary at PLAN.

<!-- onboarding is a platform-NEUTRAL journey skill (like the cross-family a11y/i18n): no per-platform Companion block. Its "companion" is whatever framework core the plan names on hand-off. -->

Use this skill when

Any first-contact "add CometChat" intent, on ANY stack: "add chat", "add cometchat", "add chat to my app", "add voice/video calling", "integrate cometchat". The router (cometchat) ALWAYS routes here FIRST — a mandatory gate. It runs before ANY framework core so the developer gets discover → understand → plan before a line is written. (An upgrade request — "upgrade my v6 UI Kit to v7" — is reconciliation, not onboarding; the router sends that straight to migration. And a re-entry on an already-integrated repo short-circuits: see §Re-entry.)

What this skill does — and only this (the four beats)

Run the four beats in order, as a CONSULTATIVE conversation (senior-engineer tone: recommend with a reason, surface trade-offs, never a blank form). Nothing is written to the user's code in ANY beat — the first write happens only AFTER beat 4's approval, inside the framework core. The final output is PRODUCTION-READY (the core's contract guarantees it).

The build model — UI Kit first, SDK per-feature fallback (NO "which approach?" question). A renderable app on a platform with a shipped UI Kit ALWAYS gets the UI Kit as its UI layer (fastest path to a production-ready surface). There is NO "UI Kit vs SDK" architecture choice to make. Instead, PER FEATURE: if the UI Kit has a component/prop for it → use the component; if it does NOT → call the platform's Chat SDK method directly (already installed under the UI Kit — init/login use it). The SDK is the FALLBACK for what the UI Kit doesn't expose (AI agents, campaigns, advanced/AI moderation, transient messages, bots, webhooks, ...), looked up in the detected family's core references/docs-map.md → SDK docs (references/platforms.md). The ONLY exception: a backend/no-DOM/non-renderable context has no UI layer — there the SDK is the whole build; say so honestly.

1. DETECT everything (environment + the WHOLE current repo)

Run the detect probe (above), then READ THE REPO for the rest (on web: package.json deps/scripts, the lockfile, framework config files and source; on iOS: *.xcodeproj/*.xcworkspace, Package.swift, a Podfile as a signal only — references/platforms.md). Capture, framework-agnostically, degrading gracefully when a signal is absent (record it null, never guess):

  • Framework & build: framework · framework_version · bundler · router · ssr_strategy (ssr/csr/islands) · env_prefix (VITE_/NEXT_PUBLIC_/...) · package_manager (from the lockfile) · language (TS/JS) · project_name (plus mobile version fields for expo/RN/android/flutter).
  • App integration state: installed UI Kit + version_conflict (a major other than the family's target — React v7, Angular v5, RN v5, iOS v5, Android v6, Flutter v6; peers.yaml) · existing CometChat integration · credential presence (an existing .cometchat/config.json or *_COMETCHAT_APP_ID env).
  • App architecture (infer from source, null when absent): auth system (nextauth / clerk / firebase / auth0 / supabase / custom) · styling / design system (tailwind / css-modules / mui / styled-components / chakra) · state management (redux / zustand / mobx / recoil / context).
  • Docs MCP: no search_cometchat_docs tool? Before the questions, say how to connect it (RULES.md → Canonical doc channel).

version_conflict STOP still applies HERE. If detection shows a UI Kit major other than the family's target for an add request, STOP and surface it in the plan (reconcile first — RULES.md); do not hand off a build over a mixed-major repo. If CometChat is already wired for THIS major → Re-entry (below). A signal being absent is DATA, not a blocker. Missing auth ⇒ recommend the dev Auth-Key path + a note to add prod auth later; missing framework ⇒ record it and (per §Non-React) state the platform's core isn't built yet. Never fabricate a signal, never stall on one.

2. UNDERSTAND — the features + design conversation (each question WITH a recommended default from the repo)

A SHORT, consultative Q&A (clarification contract: ask and wait); every question carries a repo-inferred recommendation so the developer confirms rather than composes:

  1. Archetype / shape — 1:1/marketplace · support · community/groups · full-messenger · embedded. Infer from routes (seller/product → 1:1; /support → support; /community//groups → community). "Detected <signal> → recommend <archetype> — keep or change?"
  2. Features — WHICH capabilities (from the detected platform's manifest — features.json react-v7 / features.angular-v5.json angular-v5 / features.ios-v5.json iOS / ... — grouped; naming only one hands the wrong menu to every other family): Core chat (1:1 + groups, messages, threads, media/attachments, typing, receipts, reactions, mentions — the last two are ON BY DEFAULT in v7 core, NOT extensions to enable — AUDIT-077) is the recommended default and always included; then offer the add-ons — voice/video calls · search · polls/stickers · translation · push notifications · AI/smart-replies · moderation · AI agents. Do NOT list reactions/mentions as add-ons (they're core), and never offer a deprecated:true feature (email-replies · e2e-encryption · live-streaming). First SUBTRACT what's already present (AUDIT-043) — detect/existing-integration for wired features, and ASK which dashboard-gated extensions are already enabled (or read them with cometchat_list_features if signed in); don't re-offer an already-on feature like translation. Ask "core chat + which of these?" Don't ask about individual components/props (the core decides those). Each chosen feature maps to a UI Kit component where one exists, or an SDK method where it doesn't (AI agents · campaigns · advanced/AI moderation · bots · webhooks · transient messages → SDK) — the plan's Feature coverage section records which, so nothing is silently dropped or hand-rolled.
  3. Design / theming — HOW it should look. Present the light/dark MODE and the palette, and ALWAYS include the AUTO option: (a) Auto — follow the device's light/dark (OS) setting — the RECOMMENDED default for a fresh app (whether the kit follows the OS BY ITSELF differs per platform — iOS does, with no host code, so do not offer to wire it there; web does not — references/platforms.md, AUDIT-004), (b) a fixed light preset, (c) a fixed dark preset, (d) match your existing design system (recommended when discovery detected Tailwind/MUI/Chakra/a token theme — reuse it), (e) a brand palette (your colors as the platform's theme tokens — CSS custom properties on web, UIColor/dynamicColor on iOS), or (f) a custom design system. All map to the UI Kit's theme tokens / customization. Recommend from the detected styling signal: none → auto + default tokens; a design system detected → auto + match. Omitting the auto / follow-system option is a defect (AUDIT-042) — the kit supports it and it's the pack's fresh-app default; never present a light-only menu.
  4. Scope / placement — smallest surface that satisfies the archetype (default) vs. the full combined app; the placement shapes differ by platform (references/platforms.md). Default to the SMALLEST reasonable production-ready surface. The archetype → capability translation is in references/archetypes.md; the feature menu is the DETECTED platform's manifest (references/platforms.md) — never offer a feature that platform does not ship. Recommend, don't interrogate.

3. PLAN — share the FULL plan artifact BEFORE anything is written

Assemble and present the plan artifact — the concrete deliverable of this skill. It MUST contain every section of the plan-completeness contract (template + contract in references/plan-artifact.md):

  1. What I found — the beat-1 discovery summary — the fields that APPLY to the detected platform (web: framework/bundler/router/SSR/pkg-mgr/env-prefix; iOS: deployment target/dependency manager/UI framework/Xcode project), plus language, auth, styling, existing-CometChat — each value or null. Do not report a field the platform does not have.
  2. What you want (feature coverage) — the confirmed intent (archetype · features · design/theming · scope) translated to CometChat capabilities (intent→capability map from references/archetypes.md; features from features.json), each tagged UI Kit component or SDK method — the UI-Kit-first / SDK-fallback split. Flag the SDK-backed ones (AI agents · campaigns · advanced moderation · bots · ...) so the core wires them from the SDK docs; nothing is silently dropped or hand-rolled.
  3. What I'll do — a NUMBERED action list (the scoped build steps, in order).
  4. Files that will change — the concrete paths/areas the build will touch (additive — APPEND, never replace).
  5. Packages — the exact package(s) the plan installs (named, with major pins; the core owns the exact coordinates).
  6. Credential + auth strategy — dev Auth Key vs prod server-minted auth token, CHOSEN from discovery (a real auth system detected ⇒ recommend the prod token path wired to it; none ⇒ dev Auth-Key path + a note to harden for prod). State it; do NOT fetch credentials here. Say in the plan that the core will OFFER to fetch App ID/Region/Auth Key from the dashboard (through the CometChat MCP: cometchat_list_apps → cometchat_get_app_credentials) or let the user paste them — so the fetch step isn't dropped on hand-off and never degrades into a "paste them yourself" TODO (AUDIT-039).
  7. The modify-or-approve gate — explicitly invite the user to EDIT the plan or approve it. Nothing is written before approval.

4. MODIFY or START — edit the plan, else hand a SCOPED directive to the core

  • The user may edit any part of the plan (change the archetype, add/drop a feature, narrow scope, switch the credential strategy) → re-render the plan and re-present the gate. Loop until they approve.
  • On approval, emit a scoped build directive and hand off:
    • Framework detected → resolve <family> from peers.yaml (React web → react-v7; Angular → angular-v5; iOS → ios; React Native/Expo → react-native; Android → android-v6, reading android_variant from gradle files for cohort; Flutter → flutter-v6) and hand off to cometchat-<family>-core with the scoped surface (archetype + features + theming + scope + credential strategy + affected files), pulling in ONLY the additional SHIPPED skills the plan names (theming → customization, framework glue → patterns, features → features, voice/video → calls, push → cometchat-<family>-push (thin, docs-first), v6→v7 upgrade → migration). The core builds UI Kit first and, for any SDK-backed feature the plan flagged (AI agents · campaigns · advanced moderation · ...), wires the SDK method looked up in cometchat-<family>-core/references/docs-map.md → SDK docs. The core owns detect-reuse, credentials, and the production-ready build. Android extra: cohort-split skills (android_variant: views → kotlin-*, compose → compose-*) pick {kotlin,compose}-{components,placement,customization}; cohort-neutral skills (features, calls, push, production, testing, troubleshooting, builder-settings, events, extensions, migration). Credentials → app/src/main/assets/cometchat-settings.json (gitignored), not .env.
    • A framework with no shipped core detected → still deliver the full discover→understand→plan, then state clearly that that platform's implementation core isn't built yet (framework-ready posture; see §Not in this pack). Do not fake an implementation.

Scoped, not the kitchen sink. The directive names the SMALLEST surface the approved plan calls for (e.g. "1:1 chat surface for the marketplace, dev Auth-Key, touch src/features/chat/*"), so the core builds that — not every component.

Calling-FIRST intent — the "add calling" decision tree

When the PRIMARY first-contact intent is calling ("add calling / voice-video / a video call" as the GOAL, not "add chat" that includes calls), run the references/calling-first.md decision tree instead of defaulting to the UI-Kit path — calling is the ONE intent where an approach choice is legitimate (standalone build-your-own-UI calling is a real product; a CHAT build still gets NO approach question). In brief: detect the UI Kit → offer prebuilt (cometchat-<family>-calls) vs standalone from scratch; if no UI Kit, ask "chat too, or calling only?"; for from-scratch, ask one-on-one (ringing) vs meet-style, then hand off to the platform's headless Calls SDK v5 skill (cometchat-js-v5-sdk web, cometchat-ios-v5-sdk iOS, cometchat-android-v5-calls-sdk Android, cometchat-react-native-v5-sdk React Native, cometchat-flutter-v5-sdk Flutter — resolved from peers.yaml, not a literal; not installed? npx @cometchat/skills add --family <platform>-calls adds it alongside) with the mode. Still run beats 1–3 + a short plan before hand-off.

The hand-off boundary (REUSE the core; do NOT fork it)

This skill does discover + understand + plan. The framework core does credentials + implement + verify. The line is BEAT 4's approval:

  • Onboarding OWNS: whole-repo discovery, intent elicitation with recommendations, the plan artifact, the modify/approve gate, the scoped directive.
  • The core OWNS (do NOT restate or fork here): credential fetch/provision + env write (references/setup-credentials.md), init→login→render, component/prop selection, the production-ready build. It REUSES this discovery (re-reads the same signals + any .cometchat config, skips re-setup) — one detection approach, two consumers.

Competitor SDK present (migrate_from non-null)

Name the vendor in the plan and offer the one-prompt migration; on "migrate"/"replace" hand straight to that entry's skill (no plan gate — it runs end-to-end). Never install CometChat alongside Sendbird/Stream silently.

Re-entry (already-integrated repo)

If beat-1 discovery shows CometChat already wired for the current major (existing_cometchat: true, no version_conflict), do NOT re-run the full journey. Summarize what's already integrated, ask what the user wants to ADD or CHANGE, and route that incremental ask straight to the framework core (or the calls/features/customization skill it names) — onboarding is the FIRST-contact front door, not a gate on every subsequent change.

Not in this pack — missing skills & not-yet-built cores (graceful-degrade posture)

Only hand off to a core/skill that SHIPS in this pack (under skills/, declared in peers.yaml). Never route to an uninstalled skill; run beats 1–3, produce the plan, and in beat 4 offer the nearest shipped alternative. React, Angular, iOS, React Native, Android and Flutter all ship FULL sets. Apply this posture only where a capability has NO shipped skill, or the platform has no peers.yaml peer (Vue today) — deliver the plan as the spec and say the skill isn't built yet. Never pretend React; never decline a family that ships. Routing table + decline wording: references/not-in-this-pack.md.

Clone of a named app ("build a <app> clone", "make it like <app>")

Load references/clone-mode.md and run it; the one-line request is complete. One short question round, research the target down to tiny details (each feature's entry → container → close), a build level L0–L6 per item, a Clone inventory in the plan, one approval, then build + compare item by item. It overrides "smallest surface" (default scope: all of L0–L4) and the hand-roll pitfall (a kit component that can't reach the target is L3/L4).

Common pitfalls

  • Writing code in beats 1–3. The first write is post-approval, in the core. Onboarding that scaffolds before the plan is approved has skipped its own gate.
  • Asking "UI Kit or SDK?" There is NO approach choice (calling-first excepted) — the UI Kit is always the UI layer, the SDK the per-feature FALLBACK inside the same build. Don't ask; map each feature to its component, or its SDK method where none exists.
  • Hand-rolling a feature that already exists. Never build custom UI/logic for something the UI Kit has a component for, OR the SDK has a method for. Check the UI Kit first (component-props.md / catalog), then the SDK docs (docs-map.md). Hand-roll ONLY when neither has it.
  • Asking blank questions, or skipping features/design. Beat 2 must cover archetype · WHICH features · HOW it looks (auto/follow-OS [default] · fixed light/dark · match design system · brand · custom) · scope, each WITH a repo-inferred recommendation. A bare "which archetype?" is under-delivery; omitting auto/follow-OS is a defect (AUDIT-042).
  • Forking the credential/detect flow. Do NOT re-implement credentials or detection here — plan them, then let the core execute (the hand-off boundary above).
  • Over-scoping the directive. Hand off the smallest surface the plan names, not the whole combined app (that's a later grow-on-request in the core).
  • Stalling on a missing signal. Absent auth/framework/styling is recorded null and flows into a recommendation — never a blocker. (version_conflict on an add IS a STOP; a missing signal is not.)

Verify before done (this skill's "done" = a good plan + a clean hand-off, NOT a running app)

Onboarding is complete when: (1) beat-1 discovery ran and every signal is captured or explicitly null; (2) every intent question (archetype · features · design/theming · scope) was asked WITH a repo-inferred recommendation and answered; (3) the plan artifact was presented containing ALL plan-completeness sections incl. Feature coverage (UI Kit component vs SDK method per feature) (references/plan-artifact.md); (4) the user approved (or edited → re-approved); (5) EITHER a scoped directive was handed to a SHIPPED core (cometchat-<family>-core), OR — where no skill ships for the platform/capability — the §Not in this pack posture was stated (honest + plan-as-spec + shipped alternative), never a hand-off to an uninstalled skill. This skill does NOT build, test, or run the app — the chosen core does the build (production-ready per its contract); testing is advisory/human unless the user asks (RULES.md).

Deep references (load ONLY when the beat needs them — keeps this file thin)

  • references/archetypes.md — the archetype → CometChat-capability map (1:1/marketplace · support · community · full-messenger · embedded) + the repo-signal → recommended-default heuristics for beat 2, and the intent→capability translation for the plan's "what you want".
  • references/plan-artifact.md — the plan-artifact TEMPLATE (fill-in) + the plan-completeness contract (the seven sections the plan MUST contain) + a worked example.
  • references/calling-first.md — the "add calling" decision tree (UI-Kit-present → prebuilt vs scratch; no-UI-Kit → chat-too? ; scratch → one-on-one vs meet → hand off per platform: web cometchat-js-v5-sdk, iOS cometchat-ios-v5-sdk, Android cometchat-android-v5-calls-sdk, React Native cometchat-react-native-v5-sdk). Load when the primary intent is calling.
  • references/not-in-this-pack.md — the graceful-degrade posture in full: the per-platform table of which skills SHIP (so a shipped family is never declined) + how to word an honest decline. Load in beat 4 when a needed skill may not exist.
  • references/clone-mode.md — the clone flow (questions + defaults, target research, build levels L0–L6, Clone inventory, compare loop). Load when the user names an app to copy.
  • references/platforms.md — the per-platform beat-1 signal columns (web · iOS · Android · React Native · Flutter) + the platform feature manifests.

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k