@salesforce/afv-skills 1.58.0 → 1.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/agentforce-bot-upgrade/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentforce-bot-upgrade
-description: "Use this skill to Upgrade Einstein Bots into Agentforce agents end-to-end in a single pass, orchestrating per-bot Agent Spec generation, planner reconciliation across bots, agentforce-generate authoring, and post-conversion .agent enhancements. TRIGGER when: user asks to migrate, upgrade, or convert one or more Einstein Bots to Agentforce; 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; the request is unrelated to Einstein Bot migration."
+description: "Use this skill to Upgrade Einstein Bots into Agentforce agents end-to-end in a single pass, orchestrating per-bot Agent Spec generation, planner reconciliation across bots, 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."
 argument-hint: "[--mode <online|offline>] [--org-alias <org-alias> --bots <bot1:v1,bot2:v2,...> | --offline-dir <offline-dir> [--bots <bot1,bot2,...>]] [--interactive <true|false>]"
 metadata:
   version: "1.0"
@@ -25,6 +25,8 @@ Run a multi-bot upgrade-and-handoff cycle:
 4. `/agentforce-generate` per Agent Spec (parallelizable)
 5. Post-conversion enhancement pass per generated Agent Script (parallelizable)
 
+**Scope — this skill only converts Einstein Bots** (`BotDefinition`/`BotVersion` chatbots) into new Agentforce agents. It does NOT migrate an existing Agentforce agent from a legacy `GenAiPlannerBundle` to an NGA `aiAuthoringBundle` — for that, use the **agentforce-generate** skill's "Migrate a Legacy Agent to Agent Script" flow.
+
 ## Inputs
 
 Inputs:

package/skills/agentforce-generate/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: agentforce-generate
-description: "Build, modify, audit, repair, optimize, debug, and deploy agents with Agentforce Agent Script. TRIGGER when: user creates, reviews, or changes .agent files or aiAuthoringBundle metadata; asks to fix AgentScript, audit an existing agent, run an AgentScript health check, common-pitfall review, or baseline-versus-candidate repair loop; changes a response, action, subagent, route, state flow, or Agent Spec; previews, debugs, deploys, publishes, or tests agents; uses sf agent generate/preview/publish/test; or manages Agentforce MCP servers, tools, assets, or authentication. DO NOT TRIGGER when: Apex, Flow, Prompt Template, Experience Cloud, or general Salesforce CLI work is unrelated to Agent Script; or the primary input is a production session or trace ID rather than an agent artifact."
+description: "Build, modify, audit, repair, optimize, debug, and deploy agents with Agentforce Agent Script. TRIGGER when: user creates, reviews, or changes .agent files or aiAuthoringBundle metadata; asks to fix AgentScript, audit an existing agent, run an AgentScript health check, common-pitfall review, or baseline-versus-candidate repair loop; changes a response, action, subagent, route, state flow, or Agent Spec; migrates or upgrades a legacy GenAiPlannerBundle Agentforce agent (NOT an Einstein Bot) to an aiAuthoringBundle (Agent Script) agent; previews, debugs, deploys, publishes, or tests agents; uses sf agent generate/preview/publish/test; or manages Agentforce MCP servers, tools, assets, or authentication. DO NOT TRIGGER when: Apex, Flow, Prompt Template, Experience Cloud, or general Salesforce CLI work is unrelated to Agent Script; the source is an Einstein Bot (BotDefinition/BotVersion) — use agentforce-bot-upgrade; or the primary input is a production session or trace ID rather than an agent artifact."
 metadata:
   version: "0.11"
   domains: ["Agentforce"]
   minApiVersion: "66.0"
   relatedSkills:
+    - "agentforce-bot-upgrade"
     - "agentforce-observe"
     - "agentforce-test"
     - "automation-flow-generate"
@@ -351,6 +352,25 @@ creation, execution, and result analysis. First map the Agent Spec and all
 reachable routes/actions into coverage targets. Confirm before adding security
 tests or running tests that can invoke live actions.
 
+### Migrate a Legacy Agent to Agent Script
+
+User wants to upgrade a legacy `GenAiPlannerBundle` agent into an NGA `AiAuthoringBundle` (Agent Script) agent. May say "migrate my legacy agent", "upgrade to the new builder", "convert agent", "start migration", or mention `genAiPlannerBundle` / `aiAuthoringBundle` migration. (Distinct from Einstein **Bot** upgrades — this covers existing Agentforce **agents**. To convert an Einstein **Bot** into a new agent, use the **agentforce-bot-upgrade** skill instead.)
+
+#### Required Steps
+
+Read [Upgrade a Legacy Agent to Agent Script](references/upgrade-legacy-agent-to-agentscript.md) for the full workflow, exact commands, and the NGA-vs-legacy discriminator. In brief:
+
+1. **Set up the project** — **Confirm the target org via a selectable menu — never assume the default org** (show `sf org list`, mark the default, require an explicit pick). Confirm a DX project (create one if needed); run all retrieves from inside it.
+2. **Pick the legacy agent version** — Two-screen selection: choose the agent, then a **non-NGA** version. Exclude versions whose planner `PlannerType` is `Atlas__ConcurrentMultiAgentOrchestration` (already NGA).
+3. **Migrate via the Connect API** — POST the chosen `botVersionId` to `migrateAgentToNga`. Mutating call; confirm org + id first. Run it in a **subagent** so the large response (inline `agentScript`) does not bloat context — return only `bundleVersionApiName` (+ `conversionWarnings`, `agentResponse`).
+4. **Retrieve the new bundle** — Pull the `AiAuthoringBundle` into the project (by `bundleVersionApiName`, or map `bundleVersionId → fullName` as fallback).
+5. **Analyze, optimize, iterate** — The migration is a mechanical transform that ignores Agent Script primitives. Hand off to **Comprehend an Existing Agent**, then **Optimize an Agent**, then validate/preview.
+
+#### Reference Files
+
+1. [Upgrade a Legacy Agent to Agent Script](references/upgrade-legacy-agent-to-agentscript.md) — full step-by-step workflow, commands, and discriminator logic
+2. [Core Language](references/agent-script-core-language.md) — read the migrated `.agent` structure
+
 ### Optimize an Agent
 
 1. Read [Core Language](references/agent-script-core-language.md) and scan every

package/skills/agentforce-generate/references/known-issues.md

@@ -325,6 +325,56 @@ Unresolved platform bugs, limitations, and edge cases that affect Agent Script d
 
 ---
 
+### Issue 21: Migration breaks for agents whose developer name ends in `_<digits>`
+- **Status**: WORKAROUND
+- **Date Discovered**: 2026-08-19
+- **Affects**: `migrateAgentToNga` (legacy → NGA) for any agent whose
+  `developer_name` ends in an underscore followed by digits — e.g. `Agent_01`,
+  `Support_Bot_2`, `Order_Agent_007`. The trailing `_<digits>` pattern is
+  `_\d+$`.
+- **Symptom**: The migration call itself may succeed and the migrated agent is
+  viewable/editable **in the Agent Builder UI**, but the bundle **cannot be
+  worked on from the terminal**. The versioning treatment of the
+  `AiAuthoringBundle` is wrong: the tooling conflates the `_<digits>` name suffix
+  with a bundle **version** suffix (`<name>_<version>`), so `sf project retrieve`
+  / `sf project deploy` / `sf agent validate|publish` mis-resolve the `fullName`
+  and version, and edits cannot be round-tripped.
+- **Root Cause**: `AiAuthoringBundle` uses a `<developer_name>_<version>`
+  `fullName` convention (see Issue on the retrieve/deploy folder-name trap in
+  [upgrade-legacy-agent-to-agentscript.md](upgrade-legacy-agent-to-agentscript.md)).
+  When the developer name **itself** ends in `_<digits>`, that trailing segment
+  is ambiguous with the version segment, so the bundle's version handling is
+  parsed incorrectly.
+- **Workaround**: Rename the agent's `developer_name` to break up the trailing
+  digits **before** migrating — insert a non-digit character so the name no
+  longer matches `_\d+$`. A minimal change is enough:
+  - `Agent_01` → `Agent_v01`
+  - `Order_Agent_007` → `Order_Agent_v007`
+
+  **Warning: Renaming has ripple effects.** The agent is referenced by developer name
+  in several places that must all be updated to the new name, or they break:
+  - **Email Configurations** for the Agentforce Service Agent (and any other
+    channel/config records keyed on the agent name).
+  - **Deploy configs** — `package.xml` and any `AiAuthoringBundle` /
+    `GenAiPlannerBundle` member entries that name the agent.
+  - **Integrations using the Agent API** — any external caller that targets the
+    agent by developer name.
+
+  Because of this blast radius, prefer renaming **before** the agent accrues
+  downstream references. This skill migrates agents from the terminal (`sf` CLI /
+  source-controlled workflow), so a `_<digits>` developer name is a **hard
+  blocker** for it: the rename above is mandatory before the skill can migrate the
+  agent. (The Agent Builder UI can still open a migrated `_<digits>` agent for
+  viewing — that is platform behavior, not a path this skill offers, and it does
+  not remove the terminal round-trip breakage.)
+- **Open Questions**:
+  - Will `migrateAgentToNga` / the bundle tooling be fixed to treat a
+    `_<digits>`-suffixed developer name distinctly from a version suffix?
+  - Is there a supported rename path that cascades to Email Configurations and
+    API integrations automatically?
+
+---
+
 ## Resolved Issues
 
 ### Issue 16: `connections:` (plural) wrapper block not valid — use `connection messaging:` (singular)
@@ -359,4 +409,4 @@ When an issue is resolved:
 
 ---
 
-*Last updated: 2026-03-04*
+*Last updated: 2026-08-19*