Agentforce Generate

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.

1. 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>.

1. 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.

1. 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.

1. 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., 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.

1. 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.

1. 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 and Posture & Determinism.

1. Use supported control flow. Use the canonical conditional forms and never generate a nested if, which Agentforce lint rejects. See Conditional Control Flow Syntax, then run full bundle validation.

1. 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.

1. Give each reachable branch one next outcome. Choose exactly one primary outcome: answer, ask, invoke an action, transition, refuse, or escalate. The compiler selects a subagent system.instructions override instead of the global value, and the current runtime assembles effective system and resolved reasoning text for the model. Keep authoring constructs out of model-facing text. See Instruction Resolution.

1. Use portable structural indentation. Generate new .agent files with 4 spaces per level. Preserve a consistently indented legacy file during a surgical edit, or normalize the whole file as a separate validated change.

1. Do not let prompt formatting impersonate control flow. Indentation, numbered steps, and words such as Show, Ask, Call, Set, or STOP inside | text are model instructions, not executable scope. Gate actions independently. Use one | per contiguous prompt block; repeated adjacent markers do not create stages or priority. Do not use @utils.setVariables to force a turn boundary or another reasoning iteration. Apply the checklist in Common Control-Flow Pitfalls.

1. Choose who owns each decision. Use runtime predicates when an exact machine-known fact has a consequence that must remain stable. Use model instructions when semantic intent, ambiguity, recovery, or situation-aware judgment makes flexibility more valuable. A model cannot read stored variable values unless prompt text injects them with {!@variables.X}; interpolation reveals a value but does not make the model's comparison deterministic. Apply the tradeoff test in Posture & Determinism.

1. Compile AgentScript locally first, cheaply, and visibly. For every authoring, repair, or audit task with an existing .agent file, attempt the