service-helpagent-coordinate

# service-helpagent-coordinate: Service Cloud Help Agent, guided setup Use this skill to stand up a **Service Cloud Help Agent** (an Agentforce Service Agent) on a Salesforce org from Claude Code, following the same guided flow as the Help Agent Quick Setup wizard. This is a **coordinate** skill: it orchestrates existing skills against a canonical spec — it does **not** author a new agent primitive. ## Why this skill exists Salesforce's official Help Agent template-creation API is not yet shipped. Without it, Claude has no built-in concept of "Help Agent" and would otherwise generate a generic agent. `assets/help-agent-spec.md` substitutes for the missing API: its agent script is the canonical template the eventual Quick Start UI will produce. Treat the spec as source of truth for the agent's lineage (topics, actions, instructions). ## Scope **In scope:** - Guided, four-checkpoint Help Agent setup (identity → grounding → channel → go-live) - Knowledge grounding via Agentforce Data Library (ADL) - Web Chat / Help Portal channel setup and Experience Cloud site embed - Readiness checks (licenses, Einstein Agent User, Data Cloud permission sets) **Out of scope — delegate elsewhere:** - OAuth / External Client App setup → [integration-connectivity-connected-app-configure](../integration-connectivity-connected-app-configure/SKILL.md) - Raw agent authoring with no Help Agent lineage → `agentforce-adlc:agentforce-generate` - Metadata deploy/retrieve → `platform-metadata-deploy` ## Prerequisites - Claude Code + Salesforce CLI installed and an authenticated org (see repo `README.md`) - MCP servers registered: `salesforce-api-context`, `metadata-experts`, `sobject-reads` - Salesforce Skills installed into `.agents/skills/` (or `.claude/skills/`) - **A Salesforce org with the required features enabled (or enable-able via metadata):** Agentforce, Einstein Generative AI, Knowledge, Experience Cloud, and Data Cloud. Any org shape that meets this bar works — production, sandbox, scratch, or Developer Edition. The readiness check in `assets/help-agent-spec.md` §4.0 detects each feature and enables what can be enabled; it stops with a clear message if a required capability is missing and cannot be turned on. ## Skills this coordinates The spec feeds these existing skills — do **not** author a new Help Agent skill: | Skill | Role | |---|---| | `agentforce-adlc:agentforce-generate` | Agent authoring + ADL provisioning/grounding (see its `references/data-library-reference.md`, `references/org-setup-for-adl.md`) | | `dx-org-permission-set-assign` | Data Cloud permission-set assignment | | `service-digital-engagement-channel-configure` + `service-agentforce-channel-configure` | Deploy channel (Queue routing), then PATCH `SessionHandlerId` to bind agent (see `references/channel-web-chat.md`) | | `service-digital-engagement-deployment-configure` | Embedded Service Deployment — supports both LWR (`ChatterNetworkPicasso`) and Aura (`ChatterNetwork`) sites | | `experience-lwr-site-generate` | Experience Cloud (LWR) site — used when the org has no Live LWR site yet | | `service-digital-engagement-messaging-site-integrate` | Widget placement + embed (Checkpoint 4) | ## Agentforce authoring safety preflight (MANDATORY, hard gate) This plugin-local preflight overrides any conflicting ordering or direct Agentforce CLI examples in `assets/help-agent-spec.md`. Run it once for the selected org and live plugin session **before** the existing readiness check, creating an Einstein Agent User, enabling features, generating metadata, creating or inspecting an Agentforce Data Library, loading `references/agent-script.md`, or starting any authoring, provisioning, deployment, publication, or activation operation. Resolving the target-org alias is the only work allowed before this gate. The load-bearing order is: ```text agentforce-adlc:agentforce-generate capability check ↓ non-destructive org authoring-capability probe ↓ agentforce-adlc:agentforce-generate authoring delegation ↓ later readiness, generation, ADL, and lifecycle operations ``` ### Step 1 — Resolve the owning capability `agentforce-adlc:agentforce-generate` is the plugin-qualified identity of the `agentforce-generate` skill owned by the separate `agentforce-adlc` plugin. Salesforce CLI availability does **not** prove that the plugin or skill is available. 1. Make a no-op Skill-tool dispatch to `agentforce-adlc:agentforce-generate` whose request says: `Capability availability probe only; return without reading project files, running CLI commands, or changing local or org state.` This qualified dispatch is the authoritative live-session capability check; never probe or delegate to an unqualified `agentforce-generate`, because a different workspace or flat skill could satisfy that name. The dispatch checks registration only and is not permission to begin the owning workflow. An `Unknown skill: agentforce-adlc:agentforce-generate` result means the owning capability is not registered in this session. Any normal skill response, including a usage/argument response, means it is invocable. 2. Only when the qualified dispatch is unknown, run the plugin-local, read-only installed-plugin registry check: ```bash python3 "${CLAUDE_PLUGIN_ROOT}/scripts/helpagent_dependency_preflight.py" ``` The helper invokes the documented `claude plugin list --json` registry operation internally, validates exact plugin IDs whose component before `@` is `agentforce-adlc`, and emits only a sanitized classification; never print or relay the raw registry JSON because unrelated plugin configuration may contain sensitive values. This registry result is guidance only: a cache directory, an installed entry, or `installed_enabled` does not replace the qualified Skill dispatch as proof of live-session availability. Do not infer installation from a relative cache path; installed plugin paths are marketplace- and version-dependent. 3. Stop at **Help Agent — Agentforce dependency preflight**, then honor the helper's `registryState` exactly: - `installed_enabled`: explain that `agentforce-adlc` is installed and enabled but its skill is not registered in this session. Tell the user to run `/reload-plugins` (or restart the host if reload still does not expose it), then resume this Help Agent task. - `installed_disabled`: explain that `agentforce-adlc` is installed but disabled. Recommend enabling the exact sanitized `pluginId` returned by the helper (normally `claude plugin enable agentforce-adlc@claude-plugins-official`), wait for explicit approval before changing plugin state, then tell the user to run `/reload-plugins` and resume this Help Agent task. - `missing`: explain that Agentforce authoring requires the missing `agentforce-adlc` plugin. Recommend `/salesforce-development:plugin-install agentforce-adlc`, wait for explicit approval before invoking that guarded install flow, and follow its source/nonce confirmation exactly. After installation, tell the user to run `/reload-plugins` before resuming. Do not treat a successful install as same-session skill availability. - `inconclusive`: report that installation state cannot be resolved. Give install/enable + reload guidance as alternatives, but do not mutate plugin state or guess that the capability exists. At this stop, retain and report the selected org, the checkpoint where the user entered, confirmed identity/grounding/channel choices, the local project path, and every durable identifier already produced by an earlier run (Einstein Agent User, Agentforce Data Library/library ID, `rag_feature_config_id`, agent/bundle DeveloperName, channel, deployment, and site IDs). Do not delete, recreate, roll back, or discard valid prerequisite work. The preflight itself creates no durable state, so resumption starts at the named dependency checkpoint with those facts. **There is no coordinator fallback.** When `agentforce-adlc:agentforce-generate` is unavailable, do not hand-author or reconstruct `.agent` YAML, run raw `sf agent adl` provisioning commands, call `sf agent generate authoring-bundle`, or reproduce any part of the owning skill. Stop and make the owner available. ### Step 2 — Probe the selected org without changing it Only after Step 1 proves `agentforce-adlc:agentforce-generate` invocable, run the plugin-local probe: ```bash python3 "${CLAUDE_PLUGIN_ROOT}/scripts/helpagent_authoring_preflight.py" --target-org "$ORG" ``` The helper first verifies access with `sf org display --json`, then runs the documented `sf agent validate authoring-bundle --json` operation against a fixed minimal bundle in a temporary local DX project. Validation calls the Agent Script compiler but does not deploy or create/update org metadata; the temporary project is removed. This is the strongest supported non-destructive check available because the CLI has no standalone Agent Script entitlement-inspection command. Honor its JSON `outcome` exactly: | Outcome | Coordinator action | |---|---| | `ready` | The common Agent Script compiler is reachable for this org/session. Continue to Step 3. Do not claim that Service Agent, Data Cloud, Knowledge, license seats, permissions, or channels were verified; the owning skill still checks those. | | `authentication_or_org_access_failure` | Stop at **Help Agent — Agentforce authoring capability preflight**. Reauthenticate or select an accessible org, then rerun this probe. | | `agentforce_authoring_unavailable_or_not_entitled` | Stop at the same checkpoint. A documented compiler `AgentApiNotFound` / `ERROR_HTTP_404` means the authoring endpoint is unavailable for this org or region; ask the org admin or Salesforce Support to enable/onboard Agent Script authoring, then rerun. Do not relabel it as a local permission-set or CLI problem. | | `transient_cli_or_service_failure` | Stop at the same checkpoint. Preserve state and retry the probe after CLI/network/service health recovers; do not poll, generate, or provision while waiting. | | `capability_cannot_be_conclusively_verified` | Stop at the same checkpoint. Repair/update the Salesforce CLI and `agentforce-adlc` environment or obtain authoritative org-onboarding confirmation, then rerun. Never use edition, a license query, an existing Bot/Agentforce record, Data Cloud availability, or another proxy to claim entitlement passed. | For every non-ready outcome, report the helper's concise remediation, the selected org, the retained resume state listed in Step 1, and that the probe changed no org state. Do not continue unless a later run returns `ready`; an inconclusive result is a conservative stop, not a warning to ignore. Org types expose different feature and license surfaces, so the direct compiler result—not an assumed production/sandbox/scratch/Developer Edition feature set—is authoritative for this narrow gate. ### Step 3 — Delegate to the owner After and only after Steps 1 and 2 pass, delegate Agentforce-specific readiness, Agentforce Data Library work, agent metadata generation, validation, publication, and activation to `agentforce-adlc:agentforce-generate`. Pass the selected org, canonical Help Agent spec path, current checkpoint, confirmed inputs, and retained identifiers so it reuses valid work. The Help Agent skill remains the checkpoint and channel orchestrator; it consumes the owning skill's results and never substitutes coordinator-written `.agent` YAML or raw ADL provisioning. Direct `sf agent adl ...` commands in the canonical spec describe owner behavior and are not coordinator execution instructions. --- ## Workflow Run the mandatory Agentforce authoring safety preflight above first. Only after it returns `ready`, read `assets/help-agent-spec.md` — it is the authoritative flow after the plugin-local safety override and is intentionally kept small. **Do not pre-load the rest.** The heavy or conditional material is split into `references/` and read only when the flow reaches it (progressive disclosure — this is deliberate, to keep token usage low): - **`references/agent-script.md`** — the ~500-line canonical agent script + placeholder list. Load it **only when you are ready to create the agent, after Checkpoint 2** — not during Checkpoints 1, 3, or 4. - **`references/channel-web-chat.md`** — Web Chat provisioning detail. Load **only if the user picks Web Chat** at Checkpoint 3. - **`service-concierge-portal-generate`** — Help Portal / Agentforce Concierge portal deploy. **Delegate to this skill** if the user picks Help Portal at Checkpoint 3 — do not inline the portal runbook steps here. Pass `$ORG`, `$BOT_ID`, and `$BOT_DEV_NAME` as context so the skill skips its own entry-point questions. - **`references/channel-voice.md`** — Voice channel wiring detail (existing numbers only). Load only if the user picks Voice. Read the one channel file that matches the user's selection — never all three. Then run the interactive setup **without one-shotting**: walk the user through four checkpoints in order, waiting for a reply at each. ### Readiness check (silent, MANDATORY, do not reorder) This check begins only after the authoring safety preflight returns `ready`. Agentforce-specific detection, enablement, Agentforce user setup, Data Cloud access, ADL work, and authoring remain owned by `agentforce-adlc:agentforce-generate`; delegate those requirements and verify its returned results. The commands below define required outcomes and later pre-publish verification, not a fallback authorization for the coordinator when the owning skill is missing. Order is load-bearing — running step 3 before step 2 fails with `PermissionSet not found: GenieUserEnhancedSecurity` because the Data Cloud permission sets do not exist in the org until Data Cloud itself is turned on: 1. **Verify PSL seat availability, then create a dedicated Einstein Agent User for this agent.** First confirm the three required PSLs have available seats: ```bash sf data query --target-org $ORG --json \ --query "SELECT MasterLabel, TotalLicenses, UsedLicenses FROM PermissionSetLicense WHERE DeveloperName IN ('AgentforceServiceAgentUserPsl', 'GenieDataPlatformStarterPsl', 'EinsteinGPTPromptTemplatesPsl')" ``` For each, `UsedLicenses < TotalLicenses` must be true. If any PSL is at capacity, stop and surface which one is exhausted — the PSG assignment will fail and there is nothing the skill can do until a seat is freed or provisioned. If all three have capacity, create the user. Do not reuse any existing Einstein Agent User — each Help Agent gets its own. Username: `{agentDevName}_user@{orgId}.ext` (15-char org Id from `sf org display`). Email: `noreply@salesforce.com`. Profile: `Einstein Agent User` (query `SELECT Id FROM Profile WHERE Name = 'Einstein Agent User'` to get the ProfileId, then `sf data create record --sobject User`). If a user with exactly that username already exists, reuse it (idempotent). Then assign all four of the following **before publishing the agent**: - `AgentforceServiceAgentUserPsg` (Permission Set Group) — assigns three PSLs in one call: `Agentforce Service Agent User`, `Data Cloud`, and `Einstein Prompt Templates`. Use `sf org assign permsetgroup`. - `AgentforceServiceAgentSecureBase` (Permission Set) — required for all service agents. Use `sf org assign permset`. - `AgentforceKnowledgeUser` (Permission Set, `force` namespace) — required because the Help Agent uses the `knowledge:` block. Use `sf org assign permset`. - `{AgentName}_Access` (custom Permission Set) — created by `agentforce-adlc:agentforce-generate` for agent-specific Apex/object access. Verify PSL assignments landed: `SELECT PermissionSetLicense.DeveloperName FROM PermissionSetLicenseAssign WHERE Assignee.Username = '{agentDevName}_user@{orgId}.ext'` — expect `AgentforceServiceAgentUser`, `DataCloud`, `EinsteinPromptTemplates`. **Capture the username** (`{agentDevName}_user@{orgId}.ext`) — it is the value for `<default_agent_user_placeholder>` in the agent script. The agent runs as this user at runtime. **Pre-publish gate — verify before every `sf agent publish authoring-bundle` call.** Skipping this causes a masked 401→404: SFAP returns HTTP 401 "User doesn't have access to agent" when the Einstein Agent User is missing `AgentforceServiceAgentUserPsg`, and jsforce's session-refresh retry silently converts that 401 to `ERROR_HTTP_404`. Verify all four assignments are present before invoking the CLI: ```bash AGENT_USER_ID=$(sf data query --target-org $ORG --json \ --query "SELECT Id FROM User WHERE Username='{agentDevName}_user@{orgId}.ext'" \ | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])") # Must return exactly 1 row — if 0, assign before continuing sf data query --target-org $ORG --json \ --query "SELECT PermissionSetGroup.DeveloperName FROM PermissionSetAssignment \ WHERE AssigneeId='${AGENT_USER_ID}' \ AND PermissionSetGroup.DeveloperName='AgentforceServiceAgentUserPsg'" # Must return 2 rows — if any are missing, assign before continuing sf data query --target-org $ORG --json \ --query "SELECT PermissionSet.Name FROM PermissionSetAssignment \ WHERE AssigneeId='${AGENT_USER_ID}' \ AND PermissionSet.Name IN ('AgentforceServiceAgentSecureBase','AgentforceKnowledgeUser')" ``` Do not call `sf agent publish authoring-bundle` until all four assignments return non-empty results. 2. **Enable Data Cloud** — must complete before step 3 (permission sets don't exist until Data Cloud is on). If Data Cloud is not yet provisioned, offer the user the choice up front — enable and come back later, or wait through it now. 3. **CRITICAL — Assign the Data Cloud permission sets immediately after enablement.** Non-negotiable — skipping it ships an agent whose grounding returns empty `knowledgeSummary` at runtime even though ADL indexing reports SUCCESS. The PSG assigned in step 1 covers this once Data Cloud is on. ### Recognizing where the user is entering **Checkpoint 1 (agent identity) and Checkpoint 3 (channel) must always be confirmed with the user in the current conversation — never inferred from a previous session, a compacted summary, or skill arguments.** These are decisions the user owns; acting on stale context from a prior run will configure the wrong agent or the wrong channel. If the user's opening message *in the current conversation turn* explicitly names the agent and/or channel (e.g. "set up Master Yoda on Web Chat"), accept those as the inputs and confirm them before proceeding. If not stated in the current turn, ask. For the org alias: if the user has been working against a specific org in the current session, use that. Otherwise ask. **Do not assume every run starts at Checkpoint 1.** Read the opening prompt and enter at the right checkpoint: identity decided → Checkpoint 2 (grounding); grounding done → Checkpoint 3 (channel). When the prompt explicitly names or implies a later checkpoint (e.g. "set up the grounding", "wire up the web chat channel") — and states or clearly implies prior checkpoints are already done — accept those prior checkpoints as established, enter scoped at the named checkpoint, and produce a settled-facts report for it. Do NOT force a full guided-identity re-confirmation, do NOT restart at Checkpoint 1, and do NOT demand in-conversation re-confirmation of prior decisions. Values the prompt supplies for the entered checkpoint (audience → `authMode`, named site, categories) are decided, not questions to re-ask. If the opening prompt names **Voice / phone / telephony / IVR**, read `references/channel-voice.md` and follow it from the top of Checkpoint 3 as the Voice branch. ### Checkpoint 1 — Meet Your Agent Ask for four things (offer these exact defaults so the guided-decision report can enumerate them without loading `assets/help-agent-spec.md`): 1. **Agent Name** — default `Help Agent` (DeveloperName `Help_Agent`). 2. **Language** — default `en_US`. 3. **Welcome Greeting** — default `"Hi, I'm {Agent Name}. How can I help you today?"`. 4. **Tone** — default `"calm, patient, friendly service agent — warm but professional, short sentences, never robotic."` When the opener names Q&A / case management / human escalation, note explicitly that these map to the canonical four-subagent shape (Agent Router → General FAQ, Service Customer Verification, Case Management, Escalation) — do not invent a different design. ### Checkpoint 2 — Give Your Agent Context (grounding) Ask which knowledge source (Salesforce Knowledge / files / website sync). Grounding is **provisioning an Agentforce Data Library**, not designing a search — the agent's `knowledge:` block does the retrieval at runtime. This checkpoint MUST produce all five of: 1. **Delegate provisioning to `agentforce-adlc:agentforce-generate`** — it owns ADL create/index/publish. Do not hand-roll data-library metadata. 2. **A dedicated, named library** — create `Help_Agent_Knowledge`. **Never wire the stock `All_Records_and_Fields_Default`** (it sits in `NOT_SCHEDULED` on trial or preloaded sample-data orgs and returns empty `knowledgeSummary` with no error). 3. **Category selection** — for Salesforce Knowledge, query the org's Data Category Groups. Ask which categories to ground on **only in an interactive run**; for a non-interactive/scoped run, decide the sensible default (**the org's default Data Category Group**, or all groups if none is designated) and note the default explicitly in the settled-facts report's Blocking Issues line (e.g. "Knowledge data category not specified — chose the org's default group"). Do not stall the report asking. 4. **Wait-for-indexing gate** — poll and only proceed once `indexingStatus.status ∈ {COMPLETED, READY, SUCCESS}`. `NOT_SCHEDULED` is not success. 5. **Capture the `rag_feature_config_id`** (format `ARFPC_<libraryId>`) and wire it into the agent script's `knowledge:` block — never hardcode. **Anti-rule:** never respond to a grounding request by designing a SOQL/SOSL/GraphQL/Apex search over Knowledge articles. Grounding is ADL provisioning; retrieval is the agent's job at runtime. ### Checkpoint 3 — Add to Channels **First, always discover what already exists — never present only Web Chat / Help Portal / Voice as if they were the only options.** Follow `assets/help-agent-spec.md` §4.3 Step 1 in full: query every `MessagingChannel`, classify each by `<messagingChannelType>`, and surface every type present (WhatsApp, SMS, etc.), not just the three branches below. Skipping this discovery is the bug this section prevents. Deploy new channels with Queue routing (`service-digital-engagement-channel-configure`), then delegate agent wiring to `service-agentforce-channel-configure`. Branch by channel type: - **Web Chat** → read `references/channel-web-chat.md`. Create messaging channel + Embedded Service Deployment. **Ask deployment target first, before querying anything**: "own (non-Salesforce) website" (recommended default — short-circuits to the embed-snippet path) or "a Salesforce Experience Cloud site". Only if the user picks Experience Cloud, run the **query-first pattern**: ```sql SELECT Id, Name, UrlPathPrefix, SiteType, Status FROM Site WHERE SiteType IN ('ChatterNetworkPicasso', 'ChatterNetwork') AND Status = 'Active' ```