name: sf-ai-agentforce-legacy
description: >
[DEPRECATED] Creates Agentforce agents using Agent Script syntax with 100-point scoring.
For new agent development, use sf-ai-agentscript instead.
This skill remains available for maintaining existing agents built with legacy patterns.
license: MIT
compatibility: "Requires API v65.0+ (Winter '26) for deployment"
metadata:
version: "1.1.0"
author: "Jag Valaiyapathy"
scoring: "100 points across 6 categories"
hooks:
PreToolUse:
- matcher: Bash
hooks:
- type: command
command: "python3 ${SHARED_HOOKS}/scripts/guardrails.py"
timeout: 5000
PostToolUse:
- matcher: "Write|Edit"
hooks:
- type: command
command: "python3 ${SKILL_HOOKS}/agentscript-lsp-validate.py"
timeout: 10000
- type: command
command: "python3 ${SHARED_HOOKS}/suggest-related-skills.py sf-ai-agentforce-legacy"
timeout: 5000
SubagentStop:
- type: command
command: "python3 ${SHARED_HOOKS}/scripts/chain-validator.py sf-ai-agentforce-legacy"
timeout: 5000

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

1. Agent Creation: Generate complete Agentforce agents using Agent Script
2. Topic Management: Create and configure agent topics with proper transitions
3. Action Integration: Connect actions to Flows (directly) or Apex (via Agent Actions)
4. Validation & Scoring: Score agents against best practices (0-100 points)
5. 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)

Tier 3: Quick References

Cross-Skill: Testing

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?
1. sf-metadata: Custom objects/fields must exist before Apex or Flows reference them
2. sf-apex: InvocableMethod classes must be deployed before Flow wrappers call them
3. sf-flow: Flows must be created AND deployed before agents can reference them
4. sf-deploy: Deploy all metadata before publishing agent
5. 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

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:
1. Check existing agents: Glob: **/aiAuthoringBundles/**/*.agent
2. Check for sfdx-project.json to confirm Salesforce project structure
3. Create TodoWrite tasks

Phase 2: Template Selection / Design

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

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

Template Path Resolution (try in order):
1. Marketplace folder: ~/.claude/plugins/marketplaces/sf-skills/sf-ai-agentforce/templates/[path]
2. 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:
1. system: - Instructions and messages (MUST BE FIRST)
2. config: - Agent metadata (agent_name, agent_label, description, default_agent_user)
3. variables: - Linked and mutable variables
4. language: - Locale settings
5. start_agent topic_selector: - Entry point topic with label and description
6. 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: "[email protected]"
    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)

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

Thresholds

Cross-Skill Integration

MANDATORY Delegations

Integration Patterns

Complete integration guide: See actions-guide.md

Key Insights

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

1. VS Code with Agent Script Extension (Required)
2. Open VS Code → Extensions (Cmd+Shift+X)
3. Search: "Agent Script" by Salesforce

4. Install the extension

5. Node.js 18+ (Required)

6. Check: node --version
7. Install: brew install node (macOS)

Features

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

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