SF-AI-AgentScript Skill

Agent Script is the code-first path for deterministic Agentforce agents. Use this skill when the user is authoring

.agent

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

• 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

sf-ai-agentscript

Right-Size Determinism

• Determinism is a dial, not a destination.
• Use Agent Script when “mostly right” is not acceptable: gates, mandatory sequencing, explicit state transitions, compliance, or drift control.
• If a workflow is fully static and linear, use Flow or Apex instead of scripting the conversation.
• Prefer a deterministic envelope: deterministic entry/gate → flexible middle → deterministic closeout.
• More determinism is not automatically better. Start minimal, then harden only the parts that show routing drift, sequencing failures, or compliance risk.

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

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

AgentforceServiceAgent

default_agent_user

sf org create agent-user

AgentforceEmployeeAgent

agent_type

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:

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

developer_name

description

agent_type

default_agent_user

Local tooling also accepts

agent_description:

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:

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

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

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

flow://

@InvocableMethod

High-Signal Failure Patterns

Internal Error

invalid input/output parameters

else if

if

if

is_displayable: True

ACTION_NOT_IN_SCOPE

run @actions.X

run

@system_variables.user_input

@outputs.X

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

Full rubric: references/scoring-rubric.md

Official Resources

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