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 base

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., 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 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](references/instruction resolution.md). 11. 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. 12. 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](references/common control flow pitfalls.md). 13. 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](references/posture and determinism.md). 14. Compile AgentScript locally first, cheaply, and visibly. For every authoring, repair, or audit task with an existing .agent file, attempt the bundled local index/compiler before org side validation or a completion report. Run node <skill directory /scripts/index agent.mjs <agent file . If the SDK cannot load, follow [AgentScript Compiler Setup](references/agentscript toolchain.md), retry, and use its bounded npm/source fallback. Fix every severity 1 diagnostic and rerun until clean. Report the provider and exact version or commit. Org access does not replace this cheap local pass. If both local setup paths fail, continue with target org validation or a bounded static review and state compiler not used with the cause; do not stall the task or imply that a suggested future command was validation. Offline or non interactive mode does not waive this step: it prohibits network and org operations, not the bundled local compiler. 15. Keep the authoring bundle shape deployable. Under aiAuthoringBundles/<ApiName / , require exactly the matching pair <ApiName .agent and <ApiName .bundle meta.xml . Do not shorten the metadata filename to bundle meta.xml . Preserve scaffolded or retrieved metadata rather than rewriting its schema. A new CLI scaffolded bundle normally uses <bundleType AGENT</bundleType ; an existing descriptor can instead use the established fullName / type / status shape, with optional label and description . Do not create a partial hybrid or invent fields. Local compilation of the .agent file does not verify the metadata filename or XML, so check both before reporting validation success. Task Domains Choose the domain that matches the user's current objective. Read its named references before acting; the links are load instructions, not an optional bibliography. Follow only the applicable workflow and preserve any satisfied prerequisites. The normal lifecycle is design draft validate/preview explicitly approved release. Create an Agent Use for a new agent or authoring bundle. 1. Read [Design & Agent Spec](references/agent design and spec creation.md), then use an already approved, sufficiently detailed supplied design as the build contract without regenerating or reapproving it. Otherwise capture the requirements in a saved Agent Spec and obtain explicit approval. Keep new action implementations as NEEDS STUB until the user chooses whether to reuse implementations, generate them, or leave placeholders. 2. Read the applicable sections of [CLI for Agents](references/salesforce cli for agents.md) and validate the target org prerequisites before org work. For document grounding, read [Data Library](references/data library reference.md). For a voice agent, read [Voice Modality](references/voice modality reference.md) and [Voice Latency](references/voice latency heuristics.md). 3. Generate the authoring bundle with Salesforce CLI. Edit the scaffolded <ApiName .agent and preserve the matching <ApiName .bundle meta.xml . Read [Core Language](references/agent script core language.md), [Instruction Resolution](references/instruction resolution.md), and the applicable templates before writing. 4. Run the local compiler required by Rule 14. When an authenticated target org is available, also validate the authoring bundle in the org. Fix blocking diagnostics before implementing or deploying action dependencies. 5. Generate action implementations only when the user selected that path. Validate and deploy one dependency at a time. 6. Preview the draft and inspect traces using [Validation & Debugging](references/agent validation and debugging.md). Cover realistic happy, adjacent, recovery, and cancellation paths. 7. Stay in the draft loop. Publish and activate only after the release gates in Deploy, Publish, and Activate pass and the user explicitly approves. Comprehend an Existing Agent Use when the user wants to understand an existing bundle. 1. Locate the package and matching authoring bundle files. 2. Read [Core Language](references/agent script core language.md), then map the subagent graph, d

agentforce-generate