cometchat-ios— agent skill

Ground truth: CometChatUIKitSwift ~> 5 (+ CometChatCallsSDK ~> 5) — Pods/SPM .swiftinterface + ui-kit/ios. Official docs: https://www.cometchat.com/docs/ui-kit/ios/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.

Use this skill when

The user wants to add CometChat to any iOS project. Trigger phrases:

• /cometchat (or invoke the cometchat-ios skill via your agent's mechanism — keyword "cometchat" or "integrate chat" works in most agents)
• "add cometchat", "integrate cometchat", "add chat to my app"
• "add messaging", "add chat ui", "add in-app chat"
• "integrate chat in ios", "add chat to swift app"

This is the entry point for iOS integration. Do NOT invoke framework-specific skills directly — this dispatcher detects the project type first and routes to the right ones.

Supported project types:

The iOS UI Kit loads CometChatUIKitSwift via CocoaPods or Swift Package Manager, along with CometChatSDK.

How this skill works

This skill is interactive and conversational. You don't just detect the project type and dump code. You have a conversation with the developer to understand their project, their use case, and exactly where chat should go — THEN you write code that fits.

Pattern skills (loaded from your context):

• cometchat-ios-core — initialization, login, provider pattern, anti-patterns
• cometchat-ios-components — component catalog, props, composition patterns
• cometchat-ios-placement — WHERE to put chat (navigation, tabs, modals)
• cometchat-ios-theming — customizing colors, fonts, and styles
• cometchat-ios-customization — custom views, templates, formatters

Key principle: ask, don't assume. Every piece of information you need from the user should be asked explicitly. Don't guess the view controller, don't guess where the trigger button goes, don't guess the auth system.

Steps

Step 1 — Detect project type + map the project

First, check for iOS project indicators:

Detection checklist:

1. Look for .xcodeproj or .xcworkspace files
2. Check for Podfile (CocoaPods), Package.swift (SPM as a package), or SPM dep refs in *.xcodeproj/project.pbxproj (SPM via Xcode GUI)
3. Read Info.plist for app configuration
4. Check for SwiftUI indicators (@main App, ContentView.swift)
5. Check for UIKit indicators (AppDelegate.swift, SceneDelegate.swift, Storyboards)

If the project has NO `Podfile`, NO `Package.swift`, AND no SPM refs in the .xcodeproj (the default state of every freshly Xcode-created File → New → App project), STOP. You must establish a dependency-management mechanism before touching integration code. Read cometchat-ios-core § 1.0 for the two options (CocoaPods script-able, SPM Xcode-GUI) and complete that step first. Skipping this produces an integration with import CometChatUIKitSwift that cannot resolve at build time.

Then read the project yourself — this is critical.

• Podfile, Package.swift, or SPM refs in *.xcodeproj/project.pbxproj — existing dependencies
• The source directory structure — list all directories under the project
• Find the entry point: AppDelegate.swift, SceneDelegate.swift, or @main App
• Find existing view controllers or SwiftUI views
• Find the navigation structure: UINavigationController, UITabBarController, NavigationStack

Store this mental map — you'll use it throughout the conversation.

Compatibility baselines:

• iOS 13+ required for CometChat UI Kit (CometChatSDK floor is iOS 11)
• iOS 16+ required if you use calling — CometChatCallsSDK 5.x has a deployment target of iOS 16.0; a project targeting iOS 13 will fail to link the Calls SDK
• Swift 5.0+ required
• Xcode 14+ recommended

Step 2 — Set up credentials (onboarding)

Ask the user for their CometChat credentials:

Ask the user (preserve this exact shape — question, header, multiSelect, options[].label, options[].description — agents have varying primitive names but all support this structured form):

• question: "Let's set up CometChat. Do you have your credentials?"
• header: "CometChat Setup"
• multiSelect: false
• options:

1. label: "I have my App ID, Region, and Auth Key", description: "I'll paste them now"
2. label: "I need to create a CometChat account", description: "Guide me to get credentials"
3. label: "I'll set them up later", description: "Just show me the integration code"

If they have credentials: Ask for:

1. App ID (from CometChat Dashboard)
2. Region (us, eu, or in)
3. Auth Key (for development mode)

If they need to create an account: Direct them to:

"Create a free account at https://app.cometchat.com 1. Sign up and create a new app 2. Go to API & Auth Keys section 3. Copy your App ID, Region, and Auth Key Tell me when you have them."

Step 3 — Interactive requirements gathering

#### 3a. "What are you building?"

Ask the user (preserve the structured shape — question/header/multiSelect/options[].label/options[].description):

• question: "What kind of app are you building?"
• header: "Your app"
• multiSelect: false
• options:

1. label: "Messaging app", description: "Chat is the main feature — like WhatsApp, Telegram, or iMessage"
2. label: "Marketplace or platform", description: "Buyers and sellers communicate — like Airbnb or eBay"
3. label: "SaaS or productivity", description: "Team chat or support chat inside a product"
4. label: "Social or community", description: "User profiles with messaging — like a dating app or community"
5. label: "Support or helpdesk", description: "Customer-to-agent communication"
6. label: "Just exploring", description: "Quick demo — fastest path to see chat working"

If "Just exploring": Skip the rest of Step 3 and scaffold the minimal integration — one view controller showing CometChatConversations with cometchat-uid-1 pre-logged-in.

#### 3b. Show what you recommend and why

Ask: "Does this sound right, or do you want a different approach?"

#### 3c. Ask where things should go

Show the user their actual project structure — list the view controllers/views you found in Step 1.

For UIKit projects:

"I found these view controllers in your project: - MainViewController - ProfileViewController - SettingsViewController

>

Where should the messages screen be accessible from?"

For SwiftUI projects:

"I found these views in your project: - ContentView - HomeView - ProfileView

>

Where should the messages view be accessible from?"

#### 3d. Detect and ask about authentication

Look for auth libraries in the project:

• FirebaseAuth → Firebase Authentication
• AuthenticationServices → Sign in with Apple
• GoogleSignIn → Google Sign-In
• Custom auth patterns

Report what you found and ask:

If auth detected:

"I see you're using [Firebase Auth / etc.]. Here's how CometChat will work:

>

- Development (now): I'll use CometChat's Auth Key for quick testing - Production (later): Your server will mint per-user auth tokens

>

Start with dev mode for now?"

If no auth detected:

"I don't see an authentication system yet. For now, I'll set up CometChat with a hardcoded test user (cometchat-uid-1).

>

When you add auth later, you can connect them."

#### 3e. Confirm the plan

Show EXACTLY what you'll do before doing it:

"Here's what I'll create:

>

New files: - CometChatManager.swift — initialization and login handling - ChatViewController.swift — main chat interface

>

Files I'll modify: - AppDelegate.swift — add CometChat initialization - MainViewController.swift — add navigation to chat

>

Dependencies: CometChatUIKitSwift, CometChatSDK

>

Auth mode: Development (Auth Key)

>

Proceed? [y/n]"

Wait for explicit confirmation.

Step 4 — Reference pattern skills

All skills are already loaded in your context. Read and follow them directly:

1. cometchat-ios-core — initialization, login, provider pattern
2. cometchat-ios-components — component catalog, composition patterns
3. cometchat-ios-placement — placement pattern for the chosen approach
4. cometchat-ios-theming — if customization is needed

Step 5 — Write the integration

Execute the confirmed plan:

1. Add dependencies — CocoaPods or SPM
2. CometChatManager — singleton for init/login
3. Chat UI — appropriate components for the use case
4. Wire into existing project — READ each file before modifying
5. Environment setup — credentials configuration

Step 6 — Verify + show result

After writing code:

1. Verify the project builds
2. Check for any missing imports
3. Surface any common issues

Result message:

"CometChat is integrated! Here's what was set up:

>

- CometChatManager.swift ✓ - ChatViewController.swift ✓ - Dependencies added ✓

>

Next steps: 1. Run pod install (if using CocoaPods) 2. Build and run the app 3. Navigate to the chat screen

>

About the empty conversation list: Every CometChat app has 5 pre-created test users: cometchat-uid-1 through uid-5. To see chat working: 1. Open https://app.cometchat.com → your app → Users 2. Send a message from cometchat-uid-2 to cometchat-uid-1 3. Refresh the app to see the conversation"

Step 7 — Iteration menu

Ask the user (preserve the structured shape — question/header/options[].label/options[].description):

• question: "What would you like to do next?"
• header: "Next step"
• options:

1. label: "Customize look and feel", description: "Change colors, fonts, and styles"
2. label: "Add a feature", description: "Calls, reactions, polls, AI features"
3. label: "Customize a component", description: "Custom message bubbles, headers, etc."
4. label: "Set up push notifications", description: "APNs setup for message notifications"
5. label: "Set up production auth", description: "Replace dev Auth Key with server tokens"
6. label: "Troubleshoot an issue", description: "Debug common problems"
7. label: "I'm done", description: "Exit"

Hard rules

Always

• Ask, don't assume. Every integration decision should be confirmed.
• Always detect project type first. Do not assume UIKit or SwiftUI.
• NEVER replace existing project files unless the user explicitly confirms.
• ALWAYS read existing files before modifying them.
• ALWAYS show the plan and get confirmation before writing.
• For component names and properties, use the cometchat-ios-components skill — never invent from training data.

iOS-specific

• Initialize CometChat in AppDelegate or App init — before any UI renders
• Use the singleton pattern for CometChatManager
• Handle async initialization properly — don't show chat UI until init completes
• Respect iOS lifecycle — handle background/foreground transitions
• Support both light and dark mode — use CometChatTheme

Error handling

Common iOS integration errors:

Skill routing reference

Complete Skill Set

This iOS UI Kit skill set includes 9 comprehensive skills:

1. cometchat-ios (this file) — Entry-point dispatcher
2. cometchat-ios-core — Initialization, login, manager pattern
3. cometchat-ios-components — Complete component catalog
4. cometchat-ios-placement — Navigation patterns, tabs, modals
5. cometchat-ios-theming — Colors, fonts, dark mode
6. cometchat-ios-customization — Custom views, templates, formatters
7. cometchat-ios-features — Calls, reactions, polls, AI, extensions
8. cometchat-ios-push — Push notifications setup
9. cometchat-ios-production — Server-side auth, security
10. cometchat-ios-troubleshooting — Common issues and debugging