/experience-ui-bundle-agentforce-client-generate

name: experience-ui-bundle-agentforce-client-generate
description: "Use this skill when the user asks to add, embed, integrate, configure, style, or remove an agent, chatbot, chat widget, conversation client, or AI assistant in a UI Bundle project (React or Angular). TRIGGER when: project contains a uiBundles/*/src/ directory and the task involves adding or modifying a chat widget, chatbot, or conversational AI; files under uiBundles/*/src/ import AgentforceConversationClient in React `.tsx`/`.jsx` files, or use the app-agentforce-conversation-client element in Angular `.html` templates and AgentforceConversationClientComponent in `.component.ts` files; user asks to add any chat or agent functionality to a page. DO NOT TRIGGER when: user wants to create a custom agent, chatbot, or chat widget component from scratch; the project has no uiBundles directory."
metadata:
  version: "1.2"
  cliTools:
    - tool: ["npm"]
      semver: ">=9.0.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

Managing Agentforce Conversation Client

This skill is **framework-agnostic**: it supports both React and Angular UI Bundle apps. The Agentforce client ships as two feature packages that wrap the same Lightning Out glue — pick the one matching the app's framework (detected in Step 0):

| Framework | Feature package | Element | Component symbol | |-----------|-----------------|---------|------------------| | React | `@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client` | `<AgentforceConversationClient />` | `AgentforceConversationClient` | | Angular | `@salesforce/ui-bundle-template-feature-angular-agentforce-conversation-client` | `<app-agentforce-conversation-client>` | `AgentforceConversationClientComponent` |

**HARD CONSTRAINT:** NEVER create a custom agent, chatbot, or chat widget component. ALL such requests MUST be fulfilled by importing and rendering the existing framework-appropriate component (React `<AgentforceConversationClient />` or Angular `<app-agentforce-conversation-client>`) from its feature package as documented below. If a requirement is unsupported by the component's props/inputs, state the limitation — do not improvise an alternative.

Prerequisites

Before the component will work, the following Salesforce settings must be configured by the user. ALWAYS call out the prequisites after successfully embedding the agent.

**Trusted domains (required only for local development):**

• Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
• Local development: `localhost:<dev-server-port>` — React (Vite) defaults to `localhost:5173`; the Angular template may use a different port (check the app's dev-server config, e.g. `localhost:5174`). Add whichever port the app actually runs on.
• **Warning:** Remove this trusted domain entry before deploying to production.

Instructions

Step 0: Detect the app framework

Determine whether the target UI Bundle app is **React** or **Angular** before doing anything else — it drives discovery, import, element syntax, and prop binding in every step below.

Run the bundled detector against the app (or uiBundle) root. It performs the detection deterministically and prints exactly one token — `react`, `angular`, `ambiguous`, or `unknown`:

bash "<skill_dir>/scripts/detect-framework.sh" "<app-or-uiBundle-root>"

The detector combines: an `angular.json` at/above the root; `@angular/core` / `react` in any non-`node_modules` `package.json`; and source-file signatures (`*.component.ts`, `app.routes.ts`, or `@Component`-decorated classes for Angular; `*.tsx`/`*.jsx` for React).

Act on the result:

• `react` or `angular` → use that framework. **Do NOT ask the user** — the detection is deterministic.
• `ambiguous` (both frameworks detected) or `unknown` (neither) → ask the user which framework the app uses before proceeding.

Carry the resolved framework through the remaining steps.

Step 1: Check if component already exists

Search for existing usage across all app files (not implementation files). Use the grep for the detected framework:

**React:**

grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules

**Angular:**

grep -rn "app-agentforce-conversation-client" --include="*.html" --exclude-dir=node_modules
grep -rn "AgentforceConversationClientComponent" --include="*.ts" --exclude-dir=node_modules

**Important:** Look for the files that USE the element (for example, shared shells/layouts, route components, or feature pages) — for Angular the `<app-agentforce-conversation-client>` tag lives in a `*.html` template and the component is registered in the host's `imports: [...]`. Do NOT open the component *implementation* files:

• React: `AgentforceConversationClient.tsx` / `AgentforceConversationClient.jsx`
• Angular: `conversation.ts`, `conversation.html`, `__inherit__conversation.ts`, `agentforce-embed.service.ts`

**If multiple files found:** Ask the user which component file they are referring to. Do not proceed until clarified.

**If found:** Read the file and check the current `agentId` value.

**Agent ID validation rule (deterministic):**

• Valid only if it matches: `^0Xx[a-zA-Z0-9]{15}$`
• Meaning: starts with `0Xx` and total length is 18 characters

**Decision:**

• If `agentId` matches `^0Xx[a-zA-Z0-9]{15}$` and user wants to update other props → Go to Step 4 (update props)
• If `agentId` matches `^0Xx[a-zA-Z0-9]{15}$` and user asks to "embed" or "add" the chat client → Inform: "The Agentforce Conversation Client is already embedded in `<file>` with agent ID `<agentId>`. Would you like to change the agent or update other props?"
• Change agent → Step 2
• Update props → Step 4b
• If `agentId` is missing, empty, or does NOT match `^0Xx[a-zA-Z0-9]{15}$` → Continue to Step 2 (need real ID)
• If not found → Continue to Step 2 (add new)

**If user reports an error:**

If the user says the component is "not wo