4848ecc844
Three findings from wiring an Agent Script service agent to an apex://
invocable (API v67.0, sf CLI 2.145.6):
1. `sf agent validate authoring-bundle` returns success:true for an action
param with the wrong numeric type. Only the server-side check during the
publish step catches it, so a green validate is not evidence the action
I/O types are correct.
2. Apex Integer and Apex Decimal do not behave the same. An Integer param
as bare `number` is rejected at publish; a Decimal output as bare
`number` publishes and runs correctly. The existing "bare number fails
at publish in action inputs/outputs" note reads as universal, which
sends authors hunting for a complex type a Decimal does not need.
3. Preview started with --api-name writes trace files containing only {}.
Only the --authoring-bundle path produces readable traces. This is not
academic: a service agent cannot always be previewed via
--authoring-bundle, leaving --api-name as the only option and making the
"read the trace after every utterance" rule unsatisfiable. Documented a
discriminating-value fallback for that case.
All additive; no existing guidance removed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
||
|---|---|---|
| .. | ||
| assets | ||
| references | ||
| scripts | ||
| README.md | ||
| SKILL.md | ||
Agentforce Development Skill
A skill for developing Agentforce agents with Agent Script.
What This Skill Covers
The skill routes agent work across the full lifecycle:
| Domain | What It Handles |
|---|---|
| Create an Agent | Agent Spec design, environment checks, bundle generation, draft authoring |
| Modify an Agent | Subagent/action changes, instruction refinement, flow updates |
| Diagnose Compilation Errors | Error capture, classification, targeted fixes |
| Diagnose Behavioral Issues | Trace-based debugging, routing/action analysis |
| Deploy / Release | Draft iteration, deploy, explicit publish + activate |
| Test an Agent | Coverage design, spec creation, run analysis |
Skill Structure
agentforce-generate/
├── SKILL.md # Execution router and hard rules
├── references/ # Domain guidance and adjacent operational docs
│ ├── patterns-by-requirement.md
│ ├── posture-and-determinism.md
│ ├── agent-design-and-spec-creation.md
│ ├── architecture-patterns.md
│ ├── agent-script-core-language.md
│ ├── salesforce-cli-for-agents.md
│ ├── agent-validation-and-debugging.md
│ ├── deploy-reference.md
│ ├── agent-metadata-and-lifecycle.md
│ ├── data-library-reference.md
│ ├── ... (additional references)
├── assets/ # Templates, examples, and reusable snippets
│ ├── agent-spec-template.md
│ ├── bundle-meta.xml
│ ├── invocable-apex-template.cls
│ ├── agents/ # Complete agent templates (including router-first)
│ └── patterns/ # Reusable implementation patterns
How It Works
SKILL.md acts as the router. It maps user intent to task domains and required references, then enforces hard rules for safe execution.
Core rules include:
- Always
--jsonon everysfCLI command - Diagnose before you fix — preview with live actions and read traces before modifying code
- Spec approval is a hard gate — never proceed past Agent Spec creation without user approval
- Draft-first lifecycle — iterate in draft by default; publish/activate only with explicit user confirmation
Prerequisites
- Salesforce org with Agentforce license
- API version 66.0+ (Spring '26)
- Einstein Agent User (for service agents)
- Salesforce CLI v2.x (
sfcommand) - Claude Code (or compatible AI coding agent)
Installation
Copy the agentforce-generate folder into your project's .claude/skills/ directory:
your-project/
└── .claude/
└── skills/
└── agentforce-generate/
├── SKILL.md
├── references/
└── assets/
Restart Claude Code after installation.
Key References
- Pattern selection: references/patterns-by-requirement.md
- Posture guidance: references/posture-and-determinism.md
- Design/spec workflow: references/agent-design-and-spec-creation.md
- Architecture mechanics: references/architecture-patterns.md
- Core language: references/agent-script-core-language.md
- Validation/debugging: references/agent-validation-and-debugging.md
- Reference index and consolidation notes: references/reference-map.md
Version
Current version: 0.6.1 (2026-05-20). See references/version-history.md for the full changelog.
Credits
This skill integrates knowledge from the following sources:
Jag Valaiyapathy (sf-skills, MIT License) — Known issues catalog, production gotchas, agent access and permissions guide, and deployment patterns. Integrated starting in v0.4.2.
Hua Xu (Salesforce APAC FDE team) — Open-gate routing pattern from Kogan agent deployment.
Salesforce DevRel (agent-script-recipes) — Canonical Agent Script examples used as grounding material.
Dylan Zeigler, AI Platform (llm-utils) — Agent Script playground used as reference source.
License
Apache-2.0