name: sf-ai-agentforce description: > Creates Agentforce agents using Agent Script syntax with 100-point scoring. Use when building AI agents, defining topics and actions, or deploying AiAuthoringBundle (v65+) or GenAiPlannerBundle (v65+) metadata. license: MIT compatibility: "Requires API v65.0+ (Winter '26) for deployment" metadata: version: "1.0.0" author: "Jag Valaiyapathy" scoring: "100 points across 6 categories"

sf-ai-agentforce: Agentforce Agent Creation with Agent Script

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)

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:

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

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

sf-ai-agentforce

$ Installer