/agentforce-generate

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; 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"
    - "integration-connectivity-generate"
    - "platform-apex-generate"
    - "platform-metadata-deploy"
  cliTools:
    - tool: ["corepack"]
      semver: ">=0.25.0"
    - tool: ["curl"]
      semver: ">=7.0.0"
    - tool: ["git"]
      semver: ">=2.0.0"
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["node"]
      semver: ">=20.0.0"
    - tool: ["npm"]
      semver: ">=9.0.0"
    - tool: ["pnpm"]
      semver: ">=8.0.0"
    - tool: ["python3"]
      semver: ">=3.10.0"
    - tool: ["sf"]
      semver: ">=2.139.6"

Agent Script Skill

What This Skill Is For

This skill is for developing Agentforce agents, primarily with Agent Script, Salesforce's scripting language for AI agents.

Org-backed workflows require an Agentforce license, API v66.0 or later, and an Einstein Agent User. Static authoring and review can proceed without org access.

**CRITICAL:** Agent Script is NOT AppleScript, JavaScript, Python, or any other language. Do NOT confuse Agent Script syntax or semantics with any other language you have been trained on.

Agent Script agents are defined by `AiAuthoringBundle` metadata: an `<ApiName>.agent` file (agent behavior) plus a sibling `<ApiName>.bundle-meta.xml` file (bundle metadata). The directory and both filenames must use the same case-sensitive API name; a literal `bundle-meta.xml` filename is not deployable. Actions can be implemented with invocable Apex, autolaunched Flows, Prompt Templates, and other supported types.

This skill covers the full Agent Script lifecycle: designing agents, writing Agent Script code, validating and debugging, deploying and publishing, and testing.

How to Use This Skill

This file maps user intent to task domains and relevant reference files in `references/`. Treat this file as the execution router for end-to-end agent development, and use references for deep detail.

Identify user intent from task descriptions. Read only the reference explicitly required by the active step or needed for the current decision. Every **Reference Files** section is a lookup index, not a preload list; do not load files for later or inapplicable steps.

For a comprehensive health check, common-pitfall audit, or audit-fix-evaluate loop over an existing agent, use the **Audit and Repair an Existing Agent** task domain below as part of the same authoring lifecycle.

Rules That Always Apply

1. **Always `--json`.** ALWAYS include `--json` on EVERY `sf` CLI command. Do NOT pipe CLI output through `jq` or `2>/dev/null`. Read the full JSON response directly — LLMs parse JSON natively.

2. **Verify target org.** Before any org interaction, run `sf config get target-org --json` to confirm a target org is set. If none configured, ask the user to set one with `sf config set target-org <alias>`.

3. **Diagnose in proportion to the change.** For syntax or local static defects, run the supported local parser/compiler first, then add target-org validation when available. For behavioral defects, preserve a baseline and use preview plus traces. For a Surface repair, freeze the exact accepted edit list, then inspect the final diff and revert every other hunk, including block-scalar or metadata normalization. In a smallest-change repair, keep optional cosmetic findings advisory unless the user explicitly includes cleanup in scope; valid syntax with no diagnostic or use-case consequence is not an extra repair. Simulation can establish routing and action selection; use `--use-live-actions` only with explicit approval, a verified non-production environment, and safe test data. Do not claim an external effect from simulation or response text. See [Validation & Debugging](references/agent-validation-and-debugging.md).

4. **Use a proportionate spec gate.** Obtain explicit Agent Spec approval for greenfield agents and Structural or Rewrite changes. A user-authorized, well-specified local repair does not require recreating or reapproving the entire spec; record the affected use case and preserve the existing design. When the user supplies a sufficiently detailed design and explicitly says it is already approved, treat that as the approved spec: do not recreate it or stop for another approval unless requirements are missing or materially change.

5. **Don't stall.** After a step completes successfully, announce the next step and start it. Do not wait for the user to say "what's next" or "ok, continue." Checkpoints that require explicit user approval include: (a) Agent Spec approval when required by Rule 4, (b) the pre-Publish CHECKPOINT, (c) destructive or consequential external operations, and (d) any A/B branch the skill explicitly surfaces (e.g.,