Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-bot-upgrade

agentforce-bot-upgrade

Flagged

Use this skill to upgrade Einstein Bots into Agentforce agents end-to-end in a single pass, orchestrating per-bot Agent Spec generation, agentforce-generate authoring, and post-conversion .agent enhancements. TRIGGER when: user asks to migrate, upgrade, or convert one or more Einstein Bots (BotDefinition/BotVersion chatbots) to Agentforce agents; runs a multi-bot bot-to-agent upgrade; needs Einstein Bot metadata turned into Agent Spec handoffs and generated .agent agents; convert bots to agents; upgrade my service bots; move bots to Agentforce. DO NOT TRIGGER when: user already has an approved Agent Spec and only wants direct .agent authoring, deploy, test, or observe flows; user wants to migrate or upgrade an EXISTING Agentforce agent from a legacy GenAiPlannerBundle to an NGA aiAuthoringBundle (that is agentforce-generate's 'Migrate a Legacy Agent to Agent Script' flow, not an Einstein Bot upgrade); the request is unrelated to Einstein Bot migration.

references/input-contract.md

View on GitHub
# Input Contract

## Mode Selection

Input mode is selected from `--mode <online|offline>`:

1. **Online (org-backed retrieval)** — Use org alias + bot identity, then fetch metadata/dependencies via SF CLI.
2. **Offline (local metadata input)** — Use provided local metadata/artifacts directly without org fetch.

If `--mode` is omitted, default to **online**.
Only ask the user to clarify mode when provided inputs are insufficient or contradictory for the inferred/default mode. When `--interactive=false`, do not ask — proceed with the inferred/default mode and record the assumption; halt only if the inputs cannot support any mode.

## Supported Input Modes

### Online: Org-backed retrieval

Required inputs:

1. `--org-alias <org-alias>` — Salesforce org alias used as source context (for discovery, validation, and traceability).
2. `--bot <bot-name>` — Einstein Bot developer name/identifier to migrate.
3. `--bot-version <bot-version>` — specific version to migrate (for example: `v3`).

### Offline: Local metadata input (new)

Required inputs:

1. `--offline-dir <offline-dir>` — directory containing/associated with local bot metadata inputs.

Within `--offline-dir`, `.bot-meta.xml` and `.botVersion-meta.xml` inputs are treated as authoritative bot metadata sources for extraction/mapping.

## Offline Directory Processing Scope (Required)

When `--mode offline` is selected, process **all relevant local artifacts** in `--offline-dir` (recursively), not just bot XML:

1. Bot metadata:
   - `*.bot-meta.xml`
   - `*.botVersion-meta.xml`
2. Flow artifacts:
   - files under `flows/` (for example `*.flow-meta.xml`)
3. Apex artifacts:
   - files under `classes/` (for example `*.cls`, `*.cls-meta.xml`)
4. Misc referenced artifacts:
   - any other files referenced by bot/flow/action mappings that improve extraction/mapping fidelity

Processing rules:

1. If `flows/` exists, parse flow signatures and mappings to improve action inventory contracts.
2. If `classes/` exists, parse invocable Apex signatures (`@InvocableMethod`, `@InvocableVariable`) to improve action I/O contracts.
3. If both bot mapping and local implementation artifacts exist, prefer concrete local implementation signatures over inferred placeholders.
4. If referenced artifacts are missing locally, continue with inferred signatures and mark unresolved details in `open_questions`.
5. Never require org retrieval in offline mode.

If required inputs for the selected mode are missing, stop and ask for them before processing artifacts.

## Identity Resolution Rules

- For Online mode, use `org-alias + bot + bot-version` as the run identity key.
- For Offline mode, use `bot + bot-version` derived from provided XML metadata (or confirmed from user when not derivable).
- Do not merge artifacts from different versions in the same run.
- If source files contain a mismatched bot identity, pause and ask the user which identity is authoritative. When `--interactive=false`, do not pause — treat the identity declared in the authoritative bot metadata as the recommended default and record the assumption in `open_questions`.

## Missing/Partial Input Handling

- If action signatures are missing: keep action in inventory with `target: NEEDS_STUB`.
- If intent training data is missing: infer intent purpose from dialog labels/descriptions and mark confidence.
- If transitions are unclear: preserve as unresolved branch in `open_questions`.

## Post-Input Finalization Workflow (Required)

### Online: Org-backed retrieval

After `--org-alias + --bot + --bot-version` are finalized, execute the SF CLI sequence in:

- [SF CLI Bot Reference](sf-cli-bot-reference.md)

This is the canonical command list for:

1. Enforcing SF CLI and org access prerequisites
2. Validating bot and bot version
3. Retrieving bot metadata
4. Retrieving required Apex/Flow/ML domain dependencies

Any unresolved dependency must be recorded in `open_questions` and mapped as `NEEDS_STUB` where applicable.

### Offline: Local metadata input

When both XML files are provided (`.bot-meta.xml` + `.botVersion-meta.xml`):

1. Create a run folder in repo root named `<bot-name>-<bot-version>-agent`.
2. Copy the provided bot metadata files into that run folder:
   - `<BotName>.bot-meta.xml`
   - `<version>.botVersion-meta.xml`
3. Use that run folder as the working directory for this offline run.
4. Skip all SF CLI org validation/retrieval commands.
5. Do not fetch bot/dependency metadata from org.
6. Continue directly with extraction and mapping using all available local artifacts in `--offline-dir` as source inputs.
7. If `flows/` and/or `classes/` are present, include them in extraction before finalizing action contracts.
8. If referenced dependencies (Apex/Flow/MLDomain/etc.) are not available locally, record them as unresolved in `open_questions` and map as `NEEDS_STUB` where applicable.
9. If action signatures (Apex/Flow/etc.) cannot be fully resolved in offline mode, continue execution with best-effort signature expansion and mark unresolved fields.

All generated outputs for that run (for example `extraction-summary.json`, Agent Spec handoff, and open questions) must be written inside the same run-specific SFDX project directory for the selected mode.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall