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

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, sf agent validate, sf agent publish)
slot filling, instruction resolution, post-action loops, or FSM design

Delegate elsewhere when the user is:

maintaining legacy Setup UI / Agent Builder agents → sf-ai-agentforce
designing persona / tone / voice → sf-ai-agentforce-persona
building formal test plans or coverage loops → sf-ai-agentforce-testing

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:

Exactly one start_agent block
No mixed tabs and spaces
Booleans are True / False
No else if and no nested if
No top-level actions: block
No @inputs in set expressions
linked variables have no defaults
linked variables do not use object / list types
Use explicit agent_type
Use @actions. prefixes consistently

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

Non-Negotiable Rules

1) Service Agent vs Employee Agent

Agent type	Required	Forbidden / caution
`AgentforceServiceAgent`	Valid `default_agent_user`, correct permissions, target-org checks	Publishing without a real Einstein Agent User
`AgentforceEmployeeAgent`	Explicit `agent_type`	Supplying `default_agent_user`

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

2) Required block order

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

3) Critical config fields

Field	Rule
`developer_name`	Must match folder / bundle name
`agent_description`	Use instead of legacy `description`
`agent_type`	Set explicitly every time
`default_agent_user`	Service Agents only

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
keep post-action checks at the top of instructions: ->

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
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
sf agent activate --api-name MyAgent -o TARGET_ORG

Publishing does not activate the agent.

Deterministic Building Blocks

These execute as code, not suggestions:

conditionals
available when guards
variable checks
inline action execution
utility actions such as transitions / escalation
variable injection into LLM-facing text

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

Cross-Skill Integration

Cross-Skill Orchestration

Task	Delegate to	Why
Build `flow://` targets	sf-flow	Flow creation / validation
Build Apex action targets	sf-apex	`@InvocableMethod` and business logic
Test topic routing / actions	sf-ai-agentforce-testing	Formal test specs and fix loops
Deploy / publish	sf-deploy	Deployment orchestration

High-Signal Failure Patterns

Symptom	Likely cause	Read next
`Internal Error` during publish	invalid Service Agent user or missing action I/O	references/agent-user-setup.md, references/actions-reference.md
Parser rejects conditionals	`else if`, nested `if`, empty `if` body	references/syntax-reference.md
Action target issues	missing Flow / Apex target, inactive Flow, bad schemas	references/actions-reference.md
Preview and runtime disagree	linked vars / context / known platform issues	references/known-issues.md
Validate passes but publish fails	org-specific user / permission / retrieve-back issue	references/production-gotchas.md, references/cli-guide.md

Reference Map

Start here

Publish / runtime safety

Architecture / reasoning

Validation / testing / debugging

Examples / templates

Project documentation

Score Guide

Score	Meaning
90+	Deploy with confidence
75–89	Good, review warnings
60–74	Needs focused revision
< 60	Block publish

Full rubric: references/scoring-rubric.md