SKILL.md

$28

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.

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 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**

**Use run @actions.X only when X is a topic-level action definition with target:**

**Do not branch directly on raw @system_variables.user_input contains/startswith/endswith for intent routing**

**On prompt-template outputs, prefer is_displayable: False + is_used_by_planner: True**

**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 type

Required

Forbidden / caution

AgentforceServiceAgent

Valid default_agent_user, correct permissions, target-org checks, prefer sf org create agent-user

Publishing without a real Einstein Agent User

AgentforceEmployeeAgent

Explicit agent_type

Supplying 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

Field

Rule

developer_name

Must match folder / bundle name

description

Public docs/examples should use this config field

agent_type

Set explicitly every time

default_agent_user

Service 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:

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

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

Reference Map

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

Official Resources

Agent Script Documentation

Agent Script Recipes

Agentforce DX Guide

references/official-sources.md

sf-ai-agentscript