SF-AI-AgentScript Skill#

Agent Script is the code-first path for deterministic Agentforce agents. Use this skill when the user is authoring .agent files, building finite-state topic flows, or needs repeatable control over routing, variables, actions, and publish behavior.

Start with the shortest guide first: references/activation-checklist.md

Migrating from the Builder UI? Use references/migration-guide.md

When This Skill Owns the Task#

Use sf-ai-agentscript when the work involves:

• creating or editing .agent files
• deterministic topic routing, guards, and transitions
• Agent Script CLI workflows ( sf agent generate authoring-bundle, sf agent validate authoring-bundle, sf agent preview, sf agent publish authoring-bundle, sf agent activate)
• slot filling, instruction resolution, post-action loops, or FSM design

Delegate elsewhere when the user is:

• maintaining Builder metadata agents ( GenAiFunction, GenAiPlugin, GenAiPromptTemplate, Models API, custom Lightning types) → sf-ai-agentforce
• designing persona / tone / voice → sf-ai-agentforce-persona
• building formal test plans or coverage loops → sf-ai-agentforce-testing

If the user is in Builder Script / Canvas view but the outcome is a .agent authoring bundle, keep the work in sf-ai-agentscript.

---

Required Context to Gather First#

Ask for or infer:

• agent purpose and whether Agent Script is truly the right fit
• Service Agent vs Employee Agent
• target org and publish intent
• expected actions / targets (Flow, Apex, PromptTemplate, etc.)
• whether the request is authoring, validation, preview, or publish troubleshooting

---

Activation Checklist#

Before you author or fix any .agent file, verify these first:

1. Exactly one start_agent block
2. No mixed tabs and spaces
3. Booleans are True / False
4. No else if and no nested if
5. No top-level actions: block
6. No @inputs in set expressions
7. linked variables have no defaults
8. linked variables do not use object / list types
9. Use explicit agent_type
10. Use @actions. prefixes consistently
11. Use run @actions.X only when X is a topic-level action definition with target:
12. Do not branch directly on raw @system_variables.user_input contains/startswith/endswith for intent routing
13. On prompt-template outputs, prefer is_displayable: False + is_used_by_planner: True
14. Do not assume @outputs.X is scalar — inspect the output schema before branching or assignment

For the expanded version, use references/activation-checklist.md.

---

Non-Negotiable Rules#

1) Service Agent vs Employee Agent#

Agent typeRequiredForbidden / cautionAgentforceServiceAgentValid default_agent_user, correct permissions, target-org checks, prefer sf org create agent-userPublishing without a real Einstein Agent UserAgentforceEmployeeAgentExplicit agent_typeSupplying default_agent_user

Full details: references/agent-user-setup.md

2) Recommended top-level block convention#

Use this order for consistency in this skill's examples and reviews:

yaml

config:
variables:
system:
connection:
knowledge:
language:
start_agent:
topic:

Official Salesforce materials present top-level blocks in differing sequences, and local validation evidence indicates multiple orderings compile. Treat this as a style convention, not a standalone correctness or publish blocker.

3) Critical config fields#

FieldRuledeveloper_nameMust match folder / bundle namedescriptionPublic docs/examples should use this config fieldagent_typeSet explicitly every timedefault_agent_userService Agents only

Local tooling also accepts agent_description: for compatibility, but this skill's public docs and examples should prefer description:.

4) Syntax blockers you should treat as immediate failures#

• else if
• nested if
• comment-only if bodies
• top-level actions:
• invocation-level inputs: / outputs: blocks
• reserved variable / field names like description and label

Canonical rule set: references/syntax-reference.md and references/validator-rule-catalog.md

---

Recommended Workflow#

Recommended Authoring Workflow#

Phase 1 — design the agent#

• decide whether the problem is actually deterministic enough for Agent Script
• model topics as states and transitions as edges
• define only the variables you truly need

Phase 2 — author the .agent#

• create config, system, start_agent, and topics first
• add target-backed actions with full inputs: and outputs:
• use available when for deterministic tool visibility
• normalize raw intent/validation signals into booleans or enums before branching; avoid direct substring checks on raw user utterances for critical control flow
• keep post-action checks at the top of instructions: ->

Default authoring stance#

• Default to direct .agent authoring and edits in source control.
• Use sf agent generate authoring-bundle --no-spec only when the user wants local bundle scaffolding.
• Treat sf agent generate agent-spec as optional ideation / topic bootstrap, not the default workflow.
• Do not route Agent Script users toward sf agent create or sf agent generate template.

Phase 3 — validate continuously#

Validation already runs automatically on write/edit. Use the CLI before publish:

bash

sf agent validate authoring-bundle --api-name MyAgent -o TARGET_ORG --json

The validator covers structure, runtime gotchas, target readiness, and org-aware Service Agent checks. Rule IDs live in references/validator-rule-catalog.md.

Phase 4 — preview smoke test#

Use the preview loop before publish:

• derive 3–5 smoke utterances
• start preview with the start / send / end subcommands, not bare sf agent preview
• if you use --authoring-bundle, always choose a mode explicitly: --simulate-actions or --use-live-actions
• inspect topic routing / action invocation / safety / grounding
• fix and rerun up to 3 times

Full loop: references/preview-test-loop.md

Phase 5 — publish and activate#

bash

sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Manual activation
sf agent activate --api-name MyAgent -o TARGET_ORG

# CI / deterministic activation of a known BotVersion
sf agent activate --api-name MyAgent --version <n> -o TARGET_ORG --json

Publishing does not activate the agent. For automation, prefer --version <n> --json so activation is deterministic and machine-readable.

---

Deterministic Building Blocks#

These execute as code, not suggestions:

• conditionals
• available when guards
• variable checks
• direct set / transition to
• run @actions.X only when X is a topic-level action definition with target:
• variable injection into LLM-facing text

Important distinction:

• Deterministic: set, transition to, and run @actions.X for a target-backed topic action
• LLM-directed: reasoning.actions: utilities / delegations such as @utils.setVariables, @utils.transition, and {!@actions.X} instruction references

If you need deterministic behavior for something that is currently modeled as a reasoning-level utility, either:

• rewrite it as direct set / transition to, or
• promote it to a topic-level target-backed action and run that action

See references/instruction-resolution.md and references/architecture-patterns.md.

---

Cross-Skill Integration#

Cross-Skill Orchestration#

TaskDelegate toWhyBuild flow:// targetssf-flowFlow creation / validationBuild Apex action targetssf-apex@InvocableMethod and business logicTest topic routing / actionssf-ai-agentforce-testingFormal test specs and fix loopsDeploy / publishsf-deployDeployment orchestration

---

High-Signal Failure Patterns#

SymptomLikely causeRead nextInternal Error during publishinvalid Service Agent user or missing action I/Oreferences/agent-user-setup.md, references/actions-reference.mdinvalid input/output parameters on prompt template actionTarget template is in Draft status — activate it firstreferences/action-prompt-templates.mdParser rejects conditionalselse if, nested if, empty if bodyreferences/syntax-reference.mdAction target issuesmissing Flow / Apex target, inactive Flow, bad schemasreferences/actions-reference.mdPrompt template runs but user sees blank responseprompt output marked is_displayable: Truereferences/production-gotchas.md, references/action-prompt-templates.mdPrompt action runs but planner behaves like output is missingoutput hidden from direct display but not planner-visiblereferences/production-gotchas.md, references/actions-reference.mdACTION_NOT_IN_SCOPE on run @actions.X``run points at a utility / delegation / unresolved action instead of a topic-level target-backed definitionreferences/syntax-reference.md, references/instruction-resolution.mdDeterministic cancel / revise / URL checks behave inconsistentlyraw @system_variables.user_input matching or string-method guards are being used as control-flow-critical validationreferences/syntax-reference.md, references/production-gotchas.md@outputs.X comparisons or assignments behave unexpectedlythe action output is structured/wrapped, not a plain scalarreferences/actions-reference.md, references/syntax-reference.mdPreview and runtime disagreelinked vars / context / known platform issuesreferences/known-issues.mdValidate passes but publish failsorg-specific user / permission / retrieve-back issuereferences/production-gotchas.md, references/cli-guide.md

---

Reference Map#

Start here#

• references/activation-checklist.md
• references/syntax-reference.md
• references/actions-reference.md

Publish / runtime safety#

• references/agent-user-setup.md
• references/production-gotchas.md
• references/customer-web-client.md
• references/known-issues.md

Architecture / reasoning#

• references/architecture-patterns.md
• references/instruction-resolution.md
• references/fsm-architecture.md
• references/patterns-quick-ref.md

Validation / testing / debugging#

• references/preview-test-loop.md
• references/testing-guide.md
• references/debugging-guide.md
• references/validator-rule-catalog.md

Examples / scaffolds#

• references/minimal-examples.md
• references/migration-guide.md
• assets/
• assets/agents/
• assets/patterns/

Project documentation#

• references/version-history.md
• references/sources.md

---

Score Guide#

ScoreMeaning90+Deploy with confidence75–89Good, review warnings60–74Needs focused revision< 60Block publish

Full rubric: references/scoring-rubric.md

---

Official Resources#

• Agent Script Documentation
• Agent Script Recipes
• Agentforce DX Guide
• references/official-sources.md