⚠️ DEPRECATED: This skill has been superseded by sf-ai-agentscript.

For new agent development, use: Skill(skill="sf-ai-agentscript")

This skill remains available for maintaining existing agents built with the legacy patterns.

sf-ai-agentforce-legacy: Agentforce Agent Creation with Agent Script (Legacy)

Expert Agentforce developer specializing in Agent Script syntax, topic design, and action integration. Generate production-ready agents that leverage LLM reasoning with deterministic business logic.

Core Responsibilities

• Agent Creation: Generate complete Agentforce agents using Agent Script

• Topic Management: Create and configure agent topics with proper transitions

• Action Integration: Connect actions to Flows (directly) or Apex (via Agent Actions)

• Validation & Scoring: Score agents against best practices (0-100 points)

• Deployment: Publish agents using sf agent publish authoring-bundle

Document Map (Progressive Disclosure)

Read documents in tier order based on what you need:

Tier 2: Resource Guides (NEW)

Need Document Description

Complete syntax reference agent-script-reference.md Full Agent Script DSL, patterns, reserved words, new features

Topic design & routing topics-guide.md Topic structure, transitions, delegation, multi-topic agents

Action implementation actions-guide.md Flow/Apex actions, data types, advanced fields, slot filling

Testing approaches testing-guide.md Preview modes, Agent Testing Center, agentic fix loops

Deployment & CLI deployment-guide.md Two deployment methods, CLI commands, troubleshooting

Tier 3: Quick References

Need Document Description

CLI commands cli-guide.md sf agent commands, preview, publish

Patterns & practices patterns-and-practices.md Decision tree + best practices

Cross-Skill: Testing

Need Skill Description

Agent Testing sf-ai-agentforce-testing

Test execution, coverage analysis, agentic fix loops

Quick Links:

• Key Insights Table - Common errors and fixes

• Scoring System - 6-category validation

• Required Files Checklist - Pre-deployment verification

Official Reference:

• trailheadapps/agent-script-recipes - Salesforce's official Agent Script examples

Critical Warnings

API Version Requirement

Agent Script requires API v65.0+ (Winter '26 or later)

Before creating agents, verify:

sf org display --target-org [alias] --json | jq '.result.apiVersion'

If API version < 65, Agent Script features won't be available.

Orchestration Order

sf-metadata → sf-apex → sf-flow → sf-deploy → sf-ai-agentforce (you are here: sf-ai-agentforce)

Why this order?

• sf-metadata: Custom objects/fields must exist before Apex or Flows reference them

• sf-apex: InvocableMethod classes must be deployed before Flow wrappers call them

• sf-flow: Flows must be created AND deployed before agents can reference them

• sf-deploy: Deploy all metadata before publishing agent

• sf-ai-agentforce: Agent is published LAST after all dependencies are in place

MANDATORY Delegation:

• Flows: ALWAYS use Skill(skill="sf-flow")

• never manually write Flow XML

• Deployments: Use Skill(skill="sf-deploy") for all deployments

• Apex: ALWAYS use Skill(skill="sf-apex") for InvocableMethod classes

See docs/orchestration.md for complete workflow.

File Structure

Method Path Files Deploy Command

AiAuthoringBundle aiAuthoringBundles/[Name]/

[Name].agent

• .bundle-meta.xml

sf agent publish authoring-bundle --api-name [Name]

GenAiPlannerBundle genAiPlannerBundles/[Name]/

[Name].genAiPlannerBundle

• agentScript/[Name]_definition.agent

sf project deploy start --source-dir [path]

XML templates: See templates/ for bundle-meta.xml and genAiPlannerBundle examples.

GenAiPlannerBundle agents do NOT appear in Agentforce Studio UI.

Full deployment method comparison: See deployment-guide.md

Workflow (5-Phase Pattern)

Phase 1: Requirements Gathering

Use AskUserQuestion to gather:

• Agent purpose: What job should this agent do?

• Topics needed: What categories of actions? (e.g., FAQ, Order Management, Support)

• Actions required: Flow-based? Apex-based? External API?

• Variables: What state needs to be tracked?

• System persona: What tone/behavior should the agent have?

Then:

• Check existing agents: Glob: /aiAuthoringBundles//*.agent

• Check for sfdx-project.json to confirm Salesforce project structure

• Create TodoWrite tasks

Phase 2: Template Selection / Design

Select appropriate pattern based on requirements - see agent-script-reference.md for full list:

Pattern Use When Template

Hello World Learning / Minimal agent templates/agents/hello-world.agent

Simple Q&A Single topic, no actions templates/agents/simple-qa.agent

Multi-Topic Multiple conversation modes templates/agents/multi-topic.agent

Action-Based External integrations needed templates/components/flow-action.agent

Pattern Decision Guide: See patterns-and-practices.md for detailed decision tree.

Template Path Resolution (try in order):

• Marketplace folder: ~/.claude/plugins/marketplaces/sf-skills/sf-ai-agentforce/templates/[path]

• Project folder: [project-root]/sf-ai-agentforce/templates/[path]

Phase 3: Generation / Validation

Create TWO files at:

force-app/main/default/aiAuthoringBundles/[AgentName]/[AgentName].agent force-app/main/default/aiAuthoringBundles/[AgentName]/[AgentName].bundle-meta.xml

Required bundle-meta.xml content:

<?xml version="1.0" encoding="UTF-8"?> <AiAuthoringBundle xmlns="http://soap.sforce.com/2006/04/metadata"> <bundleType>AGENT</bundleType> </AiAuthoringBundle>

Required .agent blocks:

• system:

• Instructions and messages (MUST BE FIRST)

• config:

• Agent metadata (agent_name, agent_label, description, default_agent_user)

• variables:

• Linked and mutable variables

• language:

• Locale settings

• start_agent topic_selector:

• Entry point topic with label and description

• topic [name]:

• Additional topics (each with label and description)

Complete syntax reference: See agent-script-reference.md

Validation Report Format (6-Category Scoring 0-100):

Score: 85/100 ⭐⭐⭐⭐ Very Good ├─ Structure & Syntax: 18/20 (90%) ├─ Topic Design: 16/20 (80%) ├─ Action Integration: 18/20 (90%) ├─ Variable Management: 13/15 (87%) ├─ Instructions Quality: 12/15 (80%) └─ Security & Guardrails: 8/10 (80%)

Issues: ⚠️ [Syntax] Line 15: Inconsistent indentation (mixing tabs and spaces) ⚠️ [Topic] Missing label for topic 'checkout' ✓ All topic references valid ✓ All variable references valid

Phase 4: Deployment

Complete deployment workflow: See deployment-guide.md

Quick workflow:

1. Deploy dependencies first (flows, apex)

sf project deploy start --metadata Flow --target-org [alias]

2. ⚠️ VALIDATE AGENT (MANDATORY)

sf agent validate authoring-bundle --api-name [AgentName] --target-org [alias]

3. Deploy agent (Option A: Metadata API - recommended)

sf project deploy start --source-dir force-app/main/default/aiAuthoringBundles/[AgentName] --target-org [alias]

4. Activate agent

sf agent activate --api-name [AgentName] --target-org [alias]

NEW vs UPDATING agents: See deployment-guide.md for method selection.

Phase 5: Verification

✓ Agent Complete: [AgentName] Type: Agentforce Agent | API: 65.0+ Location: force-app/main/default/aiAuthoringBundles/[AgentName]/ Files: [AgentName].agent, [AgentName].bundle-meta.xml Validation: PASSED (Score: XX/100) Topics: [N] | Actions: [M] | Variables: [P] Published: Yes | Activated: [Yes/No]

Next Steps:

1. Open in Studio: sf org open agent --api-name [AgentName]
2. Test in Agentforce Testing Center
3. Activate when ready: sf agent activate

Phase 6: Testing (via sf-ai-agentforce-testing)

Complete testing guide: See testing-guide.md

After deploying your agent, use the sf-ai-agentforce-testing skill:

Invoke the testing skill

Skill(skill="sf-ai-agentforce-testing", args="Test agent [AgentName] and fix any failures")

The testing skill provides:

• Test spec generation from agent metadata

• 100-point test scoring across 5 categories

• Agentic fix loops - auto-fix failing tests (max 3 iterations)

• Coverage analysis for topics, actions, guardrails, escalation

Quick Reference

Minimal Working Example

system: instructions: "You are a helpful assistant. Be professional and friendly." messages: welcome: "Hello! How can I help you today?" error: "I apologize, but I encountered an issue."

config: agent_name: "My_Agent" default_agent_user: "user@example.com" agent_label: "My Agent" description: "A helpful assistant agent"

variables: EndUserId: linked string source: @MessagingSession.MessagingEndUserId description: "Messaging End User ID" RoutableId: linked string source: @MessagingSession.Id description: "Messaging Session ID" ContactId: linked string source: @MessagingEndUser.ContactId description: "Contact ID"

language: default_locale: "en_US" additional_locales: "" all_additional_locales: False

start_agent topic_selector: label: "Topic Selector" description: "Routes users to appropriate topics" reasoning: instructions: -> | Determine what the user needs. actions: go_help: @utils.transition to @topic.help

topic help: label: "Help" description: "Provides help to users" reasoning: instructions: -> | Answer the user's question helpfully.

Complete syntax and patterns: See agent-script-reference.md

Action Target Types (22+ Supported)

Type Target Syntax Recommended

Flow (native) flow://FlowAPIName

Best choice

Apex (via Flow) flow://ApexWrapperFlow

Recommended

Prompt Template generatePromptResponse://TemplateName

For LLM tasks

Standard Action standardInvocableAction://sendEmail

Built-in actions

Complete action reference: See actions-guide.md

Topic Design

Hub-and-Spoke Pattern (Recommended):

• start_agent = Hub (routes to topics)

• Topics = Spokes (feature areas)

• Each topic can transition back to hub

Complete topic patterns: See topics-guide.md

Scoring System (100 Points)

Categories

Category Points Key Criteria

Structure & Syntax 20 Valid syntax, consistent indentation, required blocks

Topic Design 20 Labels/descriptions, logical transitions, naming

Action Integration 20 Valid targets, input descriptions, no reserved words

Variable Management 15 Descriptions, required linked vars, appropriate types

Instructions Quality 15 Clear reasoning, edge cases, valid templates

Security & Guardrails 10 System guardrails, validation, error handling

Thresholds

Score Rating Action

90-100 ⭐⭐⭐⭐⭐ Excellent Deploy with confidence

80-89 ⭐⭐⭐⭐ Very Good Minor improvements suggested

70-79 ⭐⭐⭐ Good Review before deploy

60-69 ⭐⭐ Needs Work Address issues before deploy

<60 ⭐ Critical Block deployment

Cross-Skill Integration

MANDATORY Delegations

Requirement Skill/Agent Why Never Do

Flow Creation Skill(skill="sf-flow")

110-point validation, proper XML ordering, prevents errors Manually write Flow XML

ALL Deployments Skill(skill="sf-deploy")

Centralized deployment Direct CLI

Apex Creation Skill(skill="sf-apex")

@InvocableMethod generation Manually write Apex

Integration Patterns

Direction Pattern Supported

sf-agentforce → sf-flow Create Flow-based actions Full

sf-agentforce → sf-apex Create Apex via Flow wrapper Via Flow

sf-agentforce → sf-deploy Deploy agent metadata Full

sf-agentforce → sf-metadata Query object structure Full

sf-agentforce → sf-integration External API actions Via Flow

Complete integration guide: See actions-guide.md

Key Insights

Insight Issue Fix

File Extension .agentscript not recognized Use .agent

Config Field developer_name OR agent_name

Both work (aliases for same field)

Instructions Syntax instructions:-> fails Use instructions: -> (space!)

Topic Fields Missing label fails deploy Add both label and description

Linked Variables Missing context variables Add EndUserId, RoutableId, ContactId

Language Block Missing causes deploy failure Add language: block

Bundle XML Missing causes deploy failure Create .bundle-meta.xml file

Indentation Consistency Mixing tabs/spaces causes parse errors Use TABS consistently (recommended)

@variables is plural @variable.x fails Use @variables.x

Boolean capitalization true/false invalid Use True/False

⚠️ Validation Required Skipping validation causes late-stage failures ALWAYS run sf agent validate authoring-bundle BEFORE deploy

Flow Variable Names Mismatched names cause "Internal Error" Agent Script input/output names MUST match Flow variable API names exactly

Action Location Top-level actions fail Define actions inside topics

start_agent Actions Flow actions in start_agent fail in AiAuthoringBundle Use start_agent only for @utils.transition , put flow actions in topic blocks

System Instructions Pipe | syntax fails in system: block Use single quoted string only

Escalate Description Inline description fails Put description: on separate indented line

Reserved Words description as input fails Use alternative names (e.g., case_description )

⚠️ Slot Filling Reliability LLM sends empty JSON, wrong field names, or wrong values Use deterministic collection: dedicated setter action + single-use (available when @var == "" ) + null guards. See actions-guide.md

Explicit Action References LLM doesn't consistently call correct actions Reference actions in instructions: {!@actions.capture_id} . Improves LLM reliability.

Complete troubleshooting: See deployment-guide.md

Required Files Checklist

Before deployment, ensure you have:

• force-app/main/default/aiAuthoringBundles/[AgentName]/[AgentName].agent

• force-app/main/default/aiAuthoringBundles/[AgentName]/[AgentName].bundle-meta.xml

• sfdx-project.json in project root

• Valid default_agent_user in config block

• All linked variables (EndUserId, RoutableId, ContactId)

• Language block present

• ⚠️ Validation passed: sf agent validate authoring-bundle --api-name [AgentName] returns 0 errors

• All topics have label: and description:

• No reserved words used as input/output names

• Flow/Apex dependencies deployed to org first

LSP Integration (Real-Time Validation)

This skill includes Language Server Protocol (LSP) integration for real-time Agent Script validation.

Prerequisites

VS Code with Agent Script Extension (Required)

• Open VS Code → Extensions (Cmd+Shift+X)

• Search: "Agent Script" by Salesforce

• Install the extension

Node.js 18+ (Required)

• Check: node --version

• Install: brew install node (macOS)

Features

When you edit .agent files, the LSP automatically provides:

Feature Description

Syntax Validation Real-time error detection

Auto-Fix Loop Claude automatically fixes errors (max 3 attempts)

Fast Feedback ~50ms response time

Troubleshooting

"LSP server not found"

• Install VS Code Agent Script extension

• Verify: ls ~/.vscode/extensions/salesforce.agent-script-*

"Node.js not found"

• Install Node.js 18+: brew install node

Validation not triggering

• Ensure hooks are enabled in Claude Code settings

• Check: ls ~/.claude/plugins/marketplaces/sf-skills/sf-ai-agentforce/hooks/

Validation

Manual validation (if hooks don't fire):

python3 ~/.claude/plugins/marketplaces/sf-skills/sf-agentforce/hooks/scripts/validate_agentforce.py <file_path>

Scoring: 100 points / 6 categories. Minimum 60 (60%) for deployment.

Hooks not firing? Check: CLAUDE_PLUGIN_ROOT set, hooks.json valid, Python 3 in PATH, file matches pattern *.agent .

Reference & Dependencies

Resource Guides (NEW):

• agent-script-reference.md - Complete Agent Script DSL

• topics-guide.md - Topic design and routing

• actions-guide.md - Action implementation patterns

• testing-guide.md - Testing approaches

• deployment-guide.md - Deployment and CLI

• models-api.md - NEW: Native AI API (aiplatform.ModelsAPI) usage in Queueable/Batch

• custom-lightning-types.md - NEW: LightningTypeBundle for custom agent action UIs

Quick References:

• agent-script-reference.md - Full syntax + gotchas

• cli-guide.md - sf agent commands, preview, publish

• actions-reference.md - Flow, Apex, Prompt actions

• patterns-and-practices.md - Decision tree + best practices

Dependencies: sf-deploy (optional) for additional deployment options. Install: /plugin install github:Jaganpro/sf-skills/sf-deploy

Notes: API 65.0+ required | Agent Script is GA (2025) | Block if score < 60

License

MIT License. See LICENSE file in sf-ai-agentforce folder. Copyright (c) 2024-2025 Jag Valaiyapathy