---
name: service-helpagent-coordinate
description: "Use to set up, configure, ground, or go live with a Salesforce Help Agent (an Agentforce Service Agent in Service Cloud) via a guided four-checkpoint flow. Use whenever a user says any of: set up / create / build / add a help agent, service agent, or support chat agent; add or embed a chat widget on a website or Experience Cloud / LWR site; put a help agent on a channel (web chat, voice, phone, help portal); ground a help agent on Salesforce Knowledge; or wants an AI to answer customer questions, manage support cases, and escalate to a human. The right skill even when the request names only one part or references help-agent-spec.md or the Agentforce Quick Setup wizard. DO NOT TRIGGER when authoring a brand-new agent with no Help Agent lineage (use agentforce-adlc:agentforce-generate), configuring OAuth/ECAs (use integration-connectivity-connected-app-configure), or only deploying metadata (use platform-metadata-deploy)."
allowed-tools: Bash Read Write Edit Glob Grep WebFetch AskUserQuestion TodoWrite
metadata:
  version: "0.9"
  domains: ["Service", "Agentforce", "Experience"]
  minApiVersion: "67.0"
  relatedSkills:
    - "agentforce-generate"
    - "dx-org-permission-set-assign"
    - "experience-lwr-site-generate"
    - "integration-connectivity-connected-app-configure"
    - "platform-metadata-deploy"
    - "service-agentforce-channel-configure"
    - "service-concierge-portal-generate"
    - "service-digital-engagement-channel-configure"
    - "service-digital-engagement-deployment-configure"
    - "service-digital-engagement-messaging-site-integrate"
  cliTools:
    - tool: ["curl"]
      semver: ">=7.0.0"
    - tool: ["sf"]
      semver: ">=2.139.6"
    - tool: ["python3"]
      semver: ">=3.8"
---

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