sf-ai-agentforce: Standard Agentforce Platform Development#

Use this skill for the Setup UI / Agent Builder path: declarative topics, Builder-managed actions, GenAiFunction / GenAiPlugin metadata, Prompt Builder templates stored as GenAiPromptTemplate metadata, Models API usage from Apex, and custom Lightning types.

For new code-first agent development, prefer sf-ai-agentscript.

If the work produces or edits a .agent file — including Builder Script / Canvas work that results in an authoring bundle — use sf-ai-agentscript.

When This Skill Owns the Task#

Use sf-ai-agentforce when the user is:

• maintaining existing Builder-based agents
• working in Setup → Agentforce → Agents
• creating or fixing GenAiFunction, GenAiPlugin, or GenAiPromptTemplate metadata
• wiring Builder topics to Flow / Apex / Prompt Builder actions
• using Models API or LightningTypeBundle in the context of Builder-based agents

Do not use it for:

• .agent files or deterministic FSM design → sf-ai-agentscript
• agent test suites and coverage loops → sf-ai-agentforce-testing
• persona / voice design → sf-ai-agentforce-persona

---

Required Context to Gather First#

Ask for or infer:

• whether this is a Builder / Setup UI project or a code-first Agent Script project
• whether the user is editing Builder metadata or a .agent authoring bundle
• agent type: Service Agent or Employee Agent
• whether the work targets topics, actions, Prompt Builder templates, Models API, or custom Lightning types
• what supporting Flow / Apex / metadata dependencies already exist
• whether the user needs authoring help, publish help, or troubleshooting

---

Two Agentforce Paths#

PathSkillBest fitBuilder metadata pathsf-ai-agentforceDeclarative maintenance, existing Builder agents, metadata-driven action registrationAgent Script authoring bundle pathsf-ai-agentscriptCode-first .agent authoring, deterministic routing, version-controlled agent logic

If the user is starting from scratch and wants strong control over flow/state, route to Agent Script.

---

Builder Workflow Summary#

1. Confirm this is a Builder / Setup UI project
2. Pick Service Agent vs Employee Agent
3. For Service Agents, provision the running user (prefer sf org create agent-user)
4. For Employee Agents, plan visibility with a Permission Set containing <agentAccesses>
5. Define topics with strong descriptions, scope, and instructions
6. Prepare supporting actions (Flow, Apex, Prompt Builder template)
7. Configure inputs / outputs carefully
8. Validate dependencies and template status
9. Publish, then activate

Expanded workflow: references/builder-workflow.md

---

Key Platform Rules#

Topic quality matters#

Topic descriptions are routing instructions for the planner. They must be:

• specific
• scenario-based
• non-overlapping with sibling topics

Actions are wrappers around real targets#

Target typeTypical useRegistered viaFlowsafest default for Builder actionsGenAiFunctionApexcomplex business logic via @InvocableMethod``GenAiFunctionPrompt Builder templategenerated summaries / drafts / recommendationsGenAiFunction

Prompt Template vs GenAiPromptTemplate#

• Prompt Template is the plain-English / UI term used in Prompt Builder.
• GenAiPromptTemplate is the current Metadata API type for source-driven template work.
• Prefer current source format: genAiPromptTemplates/*.genAiPromptTemplate-meta.xml.
• For flexible Prompt Builder templates, plan around the 5-input maximum and consolidate inputs when needed.
• Prompt content should reference inputs with the current merge-field shape, e.g. {!$Input:TargetRecord} or {!$Input:AdditionalContext}.

Supporting metadata deploys first#

Before publishing the agent itself, deploy the supporting stack:

1. metadata / fields if needed
2. Apex if needed
3. Flows if needed
4. GenAiPromptTemplate / GenAiFunction / GenAiPlugin
5. then publish the agent

Service Agent running user#

For Service Agents, prefer the native GA command: sf org create agent-user --target-org <alias> --json Use the returned username in the running-user configuration.

Employee Agent visibility#

For Employee Agents, ensure end users receive a Permission Set containing <agentAccesses>. Without this, the agent can be active but still invisible in Lightning Experience. See ../sf-permissions/references/agent-access-guide.md.

Publish does not activate#

After publish, run sf agent activate separately. For automation, prefer sf agent activate --api-name <AgentName> --version <n> --target-org <alias> --json so the rollout is deterministic and machine-readable.

---

Metadata Guidance#

GenAiFunction#

Use when registering a single callable action. Validate:

• target exists
• target is active / deployable
• input names match the target contract
• output names match the target contract
• capability text clearly says when the action should be used

GenAiPlugin#

Use when grouping related functions into one logical package.

GenAiPromptTemplate#

Use for generated content, not deterministic business rules.

Prefer the current metadata shape:

• metadata type: GenAiPromptTemplate
• folder: genAiPromptTemplates/
• file suffix: .genAiPromptTemplate-meta.xml
• content lives under templateVersions
• use published template versions before wiring actions that depend on them

Models API#

Use when the solution belongs in Apex-driven AI orchestration rather than Builder-only actions.

Custom Lightning Types#

Use when the action needs richer structured input or output presentation.

Expanded references:

• references/metadata-reference.md
• references/genaiprompttemplate.md

---

Cross-Skill Integration#

Recommended Orchestration Order#

text

sf-metadata → sf-apex → sf-flow → sf-ai-agentforce → sf-deploy

Required delegations#

RequirementDelegate toWhyCreate / fix Flowssf-flowAction target creation and Flow validationCreate / fix Apex actionssf-apex@InvocableMethod and Apex correctnessDeploy / publishsf-deployDeployment orchestrationTest the agentsf-ai-agentforce-testingFormal test execution and assertionsEmployee Agent visibility / accesssf-permissionsPermission Set <agentAccesses> setup

---

High-Signal Failure Patterns#

SymptomLikely causeRead nextAction not available in Buildertarget metadata missing or not deployedreferences/metadata-reference.mdPrompt action fails during publish or activationtemplate is Draft, missing inputs, or old metadata shape is being usedreferences/genaiprompttemplate.mdNeed more than 5 template inputsflex template input limit hitreferences/genaiprompttemplate.mdApex AI logic times outModels API work placed in the wrong contextreferences/models-api.mdRich input/output UI not renderingLightning type config or prerequisites are incompletereferences/custom-lightning-types.mdAgent publishes but is not usableforgot explicit activationreferences/cli-commands.mdService Agent publish/runtime failuremissing or invalid running user../sf-ai-agentscript/references/agent-user-setup.mdEmployee Agent active but not visible to usersmissing <agentAccesses> permission set../sf-permissions/references/agent-access-guide.md

---

Reference Map#

Start here#

• references/builder-workflow.md
• references/metadata-reference.md
• references/genaiprompttemplate.md
• references/cli-commands.md

Terminology and template planning#

• references/prompt-templates.md
• references/models-api.md
• references/custom-lightning-types.md

Rubric#

• references/scoring-rubric.md

Cross-skill reads#

• sf-ai-agentscript
• sf-ai-agentforce-testing
• sf-flow
• sf-apex
• sf-permissions
• sf-deploy

---

Score Guide#

ScoreMeaning90+Ready to deploy80–89Strong, minor cleanup only70–79Review before deploy60–69Needs work< 60Block deployment

Full rubric: references/scoring-rubric.md