agentforce-develop

/agentforce-develop

Principles enforced: 1 (preserve the quality ceiling), 4 (spec is the artifact), 7 (institutional memory). See PRINCIPLES.md.

Copy-paste-to-agent

Build, modify, or deploy an Agentforce agent written in Agent Script. Always go through the
Agent Spec gate before writing code — the spec is the artifact (Principle 4). For backing
logic, scan sfdx-project.json package directories for existing @InvocableMethod classes,
AutoLaunchedFlows, and PromptTemplates before creating stubs (Principle 7). Validate compilation
with sf agent validate, preview behavior with sf agent preview --use-live-actions, then
publish + activate. Never proceed past spec creation without explicit user approval.
Always pass --json on every sf CLI command.

When to use this skill

Use agentforce-develop for the authoring lifecycle of an Agentforce agent:

• Designing the subagent graph and Agent Spec

• Writing or editing .agent files inside an aiAuthoringBundle

• Generating and deploying backing logic (Apex @InvocableMethod, Flows, Prompt Templates)

• Validating compilation, previewing behavior, publishing, activating

Sister skills:

• /agentforce-test — once the agent compiles, write or run test suites against it

• /agentforce-observe — once the agent is in production, analyze STDM session traces and reproduce issues

---

Rules that always apply

1. --json on every sfcommand. Always. Read the JSON directly; don't pipe through jq or 2>/dev/null and don't strip the structured output. LLMs parse JSON natively — that's the agent-native default (Principle 6).
2. Verify target org first. Run sf config get target-org --json. If none is set, ask the user before doing anything else.
3. Diagnose before you fix. When the agent misbehaves, always preview with --use-live-actions --authoring-bundle <Name>, send a representative utterance, and read the resulting trace file before editing the .agent file or backing logic. Modifying without trace evidence is the jagged-intelligence failure mode (Principle 3).
4. Spec approval is a hard gate (Principle 4). Never proceed past the Agent Spec without explicit user approval. The spec IS the contract.

---

Step 0: Pre-implementation research (parallel, Principle 7)

Before designing the agent, dispatch in parallel:

• Task sf-learnings-researcher(agent_description) — has anyone solved this agent shape before? Must-read. Returned solutions are constraints on the design, not optional context.

• Task sf-repo-research-analyst(agent_description) — what @InvocableMethod classes, AutoLaunchedFlows, PromptTemplates, and custom objects already exist in sfdx-project.json package directories? Existing backing logic should be reused, not regenerated.

• Task sf-framework-docs-researcher("Agentforce Agent Script") — confirm API version, license, and any platform constraints.

---

Step 1: Design the agent and produce an Agent Spec

The Agent Spec is the artifact. Write it before any code.

The spec must include:

• Purpose — one paragraph stating what the agent does and what it explicitly does not do.

• Agent type — employee (internal user-facing) or service (external messaging-facing). Drives environment prerequisites.

• Subagents — one per coherent topic. Name, description (with routing keywords), and the actions each subagent calls.

• Actions — for each, mark EXISTS (with file path) or NEEDS STUB (with proposed Apex/Flow/Template name and signature). Don't generate stubs for actions that already exist somewhere in the package.

• Flow control — start agent, transitions between subagents, and any available when: guards.

• Variables — names, types, scope, and which subagents read/write them.

• Verification Strategy (Principle 2) — what utterances will prove this agent works? Name at least one routing test, one happy-path action invocation test, one guardrail test (off-topic), and one safety probe.

STOP. Save the spec to docs/plans/YYYY-MM-DD-feat-<agent-slug>-spec.md. Present to the user. Do not proceed without explicit approval.

---

Step 2: Validate environment prerequisites

Pick the right path based on agent type:

• Employee agent — verify the config: block does NOT include default_agent_user, connection messaging:, or MessagingSession-linked variables. Remove if present.

• Service agent — query the org for an Einstein Agent User. If none exists, walk the user through creating one before code generation.

Do not generate the authoring bundle until environment is validated.

---

Step 3: Generate the authoring bundle

sf agent generate authoring-bundle --json --no-spec --name "<Display Label>" --api-name <Developer_Name>

This produces an aiAuthoringBundle directory under force-app/main/default/aiAuthoringBundles/<Developer_Name>/ containing a .agent file (Agent Script source) and bundle-meta.xml.

Never create .agent or bundle-meta.xml files manually. Always go through sf agent generate.

---

Step 4: Write Agent Script in the .agent file

Edit the generated .agent file. Agent Script syntax in one paragraph:

• -> introduces a logic instruction — deterministic execution, business rules, variable assignment, conditionals.

• | introduces a prompt instruction — natural-language text sent to the LLM.

• Indentation is whitespace-significant. Pick tabs OR spaces; do not mix.

• Variable interpolation: {!@variables.name}.

• Comments: # this is a comment.

Anti-patterns to avoid (Principle 5 — taste):

• Mixing personality and routing in start_agent. Persona belongs in system: instructions: only; start_agent is a router.

• Identical instructions: text across subagents. Each subagent's instructions must be distinct enough to drive routing.

• "Dead hub" subagents — defined but never reached from any transition.

• Orphan actions — listed in subagent: actions: Level 1 but never invoked from Level 2 reasoning: actions:.

Agent Script is NOT JavaScript, AppleScript, or Python. Do not let LLM training-set pattern-matching pull syntax from those languages.

---

Step 5: Validate compilation

sf agent validate authoring-bundle --json --api-name <Developer_Name>

If validation fails, fix syntax and structural errors before generating any backing logic. A .agent file that doesn't compile is not worth writing tests for.

---

Step 6: Generate backing logic (Apex / Flow / Prompt Template stubs)

For each action marked NEEDS STUB in the spec:

sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes

Replace the class body with the invocable pattern (@InvocableMethod with @InvocableVariable inputs and outputs). Then deploy:

sf project deploy start --json --metadata ApexClass:<ClassName>

Fix deploy errors before generating the next stub. One stub at a time, deploy and verify, then move on.

For Flow and Prompt Template stubs, follow the same one-at-a-time discipline.

---

Step 7: Preview with live actions and read traces (Principle 3)

sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name>

Capture the session ID, then:

sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> --utterance "<test message>"
sf agent preview end --json --authoring-bundle <Developer_Name> --session-id <ID>

Trace files land at: .sfdx/agents/<Developer_Name>/sessions/<sessionId>/traces/<planId>.json.

Confirm subagent routing, gating, and action invocations match the Agent Spec. If behavior diverges from spec, the diagnosis flow is in /agentforce-observe (jq queries against trace JSON to surface routing, action invocation, grounding, and safety scores). Return here only after correcting.

Checkpoint — do NOT proceed to publish unless ALL of the following are true:

• validate authoring-bundle passes with zero errors

• Live preview run with at least one representative utterance per subagent

• Traces confirm correct subagent routing and action invocation

• Safety probe utterances handled correctly

• User explicitly approves deployment

---

Step 8: Publish, activate, verify

# Publish — validates metadata, creates a permanent version
sf agent publish authoring-bundle --json --api-name <Developer_Name>

# Activate — makes the new version available to users
sf agent activate --json --api-name <Developer_Name>

# Verify with --api-name (NOT --authoring-bundle) post-activation
sf agent preview start --json --api-name <Developer_Name>

Every publish creates a permanent, immutable version number. Treat publish as production-grade.

---

Step 9: End-user access (employee agents only)

For employee agents, configure permission sets and assign access. For service agents, the agent is reached through messaging channels — no end-user perm assignment.

---

Capture learnings (Principle 7)

When the build is complete or you fixed a non-obvious bug, run /sf-compound to capture the learning under docs/solutions/. Agent debugging produces patterns that will not be in any general Salesforce knowledge base — this is exactly the institutional memory the plugin compounds.

---

Inspiration

This skill is adapted from forcedotcom/afv-library/skills/developing-agentforce (Apache-2.0). The upstream skill ships with eight reference files (references/agent-script-core-language.md, references/agent-design-and-spec-creation.md, references/salesforce-cli-for-agents.md, references/agent-validation-and-debugging.md, references/agent-metadata-and-lifecycle.md, references/agent-user-setup.md, references/agent-access-guide.md, references/agent-subagent-map-diagrams.md) that hold the full syntax tables and command references. For deep details — Agent Script grammar, complete CLI flag tables, permission set examples — read the upstream references. This plugin's adaptation focuses on the lifecycle gate structure and integrates with the seven-principle framework in PRINCIPLES.md.