SkillsSKILLS
AI/ML

sf-ai-agentscript▌

jaganpro/sf-skills · updated Apr 8, 2026

$npx skills add https://github.com/jaganpro/sf-skills --skill sf-ai-agentscript
summary

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.

skill.md

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:

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 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
  • 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 Read next
Internal Error during publish invalid Service Agent user or missing action I/O references/agent-user-setup.md, references/actions-reference.md
invalid input/output parameters on prompt template action Target template is in Draft status — activate it first references/action-prompt-templates.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
Prompt template runs but user sees blank response prompt output marked is_displayable: True references/production-gotchas.md, references/action-prompt-templates.md
Prompt action runs but planner behaves like output is missing output hidden from direct display but not planner-visible references/production-gotchas.md, references/actions-reference.md
ACTION_NOT_IN_SCOPE on run @actions.X run points at a utility / delegation / unresolved action instead of a topic-level target-backed definition references/syntax-reference.md, references/instruction-resolution.md
Deterministic cancel / revise / URL checks behave inconsistently raw @system_variables.user_input matching or string-method guards are being used as control-flow-critical validation references/syntax-reference.md, references/production-gotchas.md
@outputs.X comparisons or assignments behave unexpectedly the action output is structured/wrapped, not a plain scalar references/actions-reference.md, references/syntax-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 / scaffolds

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

Official Resources