/agentforce-generate

name: agentforce-generate
description: "Build, modify, optimize, debug, and deploy agents with Agentforce Agent Script. TRIGGER when: user creates, modifies, optimizes, or asks about .agent files or aiAuthoringBundle metadata; changes agent behavior, responses, or conversation logic; designs agent actions, tools, subagents, or flow control; writes or reviews an Agent Spec; wants to optimize, improve, or refactor an agent; previews, debugs, deploys, publishes, or tests agents; uses Agent Script CLI commands (sf agent generate/preview/publish/test); registers/creates/lists/updates/deletes MCP servers, whitelists/approves MCP tools, fetches MCP assets, or configures MCP authentication (sf agent mcp). DO NOT TRIGGER when: Apex development, Flow building, Prompt Template authoring, Experience Cloud configuration, or general Salesforce CLI tasks unrelated to Agent Script."
metadata:
  version: "0.11"
  minApiVersion: "66.0"
  relatedSkills:
    - "agentforce-observe"
    - "agentforce-test"
    - "automation-flow-generate"
    - "integration-connectivity-generate"
    - "platform-apex-generate"
    - "platform-metadata-deploy"
  cliTools:
    - tool: ["curl"]
      semver: ">=7.0.0"
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["npm"]
      semver: ">=9.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: a `.agent` file (agent behavior) plus `bundle-meta.xml` (bundle metadata). 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.

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 before you fix.** When validating/debugging agent behavior, ALWAYS `--use-live-actions` to preview authoring bundles. Send utterances then read resulting session traces to ground your understanding of the agent's behavior. Trace files reveal subagent selection, action I/O, and LLM reasoning. DO NOT modify `.agent` files or action implementations without this grounding. See [Validation & Debugging](references/agent-validation-and-debugging.md) for trace file locations and diagnostic patterns.

4. **Spec approval is a hard gate.** Never proceed past Agent Spec creation without explicit user approval.

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." The only checkpoints that require explicit user approval are: (a) Agent Spec approval, (b) the pre-Publish CHECKPOINT, (c) any A/B branch the skill explicitly surfaces (e.g., Data Cloud not provisioned during ADL setup). Long-running async work like ADL indexing should run in the background while the skill continues with work that doesn't depend on the result.

6. **Draft-first lifecycle.** During normal authoring, stay in draft iteration: edit `.agent` + action implementations, validate, deploy, and preview as many times as needed. Do NOT publish/activate by default. Publish + activate are explicit release actions that require the user to confirm they are ready to commit the current draft to metadata and expose it to end users.

7. **Start with one execution block and no mutable state.** A focused agent puts reasoning and actions directly in `start_agent`. Add a subagent only for a real objective, instruction, action, authority, or escalation boundary. Add persistent state only for a named deterministic consumer and give it a complete lifecycle. Ordinary continuity stays in surviving history. Apply the concrete checks in [The Zen of AgentScript](references/zen-of-agentscript.md) and [Posture & Determinism](references/posture-and-determinism.md).

8. **Use supported control flow.** Use the canonical conditional forms and never generate a nested `if`, which Agentforce lint rejects. See [Conditional Control Flow Syntax](references/agent-script-core-language.md#conditional-control-flow-syntax), then run full bundle validation.

9. **Action implementation is a user decision.** During planning/spec work, default new actions to `NEEDS STUB` placeholders. Always ask the user whether they want to scan org/project for existing implementations and/or generate new Apex/Flow/Prompt implementations before taking either path.

10. **Give each reachable bran