mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-07-30 11:43:26 +08:00
261abd679a
* @W-21955450@ Rename topic to subagent for Agent Script v2
Aligns with Agent Script v2 naming standards where `topic` is renamed
to `subagent` across all skill documentation and templates.
Changes:
- Agent Script templates: topic keyword → subagent keyword
- References: @topic.* → @subagent.*
- Documentation: Updated all skill references and guides
- Natural language references preserved in comments/descriptions
* Rename start_agent topic_selector to agent_router
Completes the topic → subagent terminology alignment by:
1. Renaming start_agent from topic_selector to agent_router (15 agent files)
2. Updating template topic declarations: topic {{placeholder}} → subagent {{placeholder}} (5 files)
3. Updating all @subagent.topic_selector references to @subagent.agent_router (35 occurrences)
4. Updating documentation: prose, examples, and diagrams (10 markdown files)
5. Updating comments to use agent_router terminology
Files affected:
- 22 agent template files
- 10 documentation/reference markdown files
- Template component files
The agent_router name is more descriptive of its actual function
(routing to different subagents) and completes the Agent Script v2
terminology standardization.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* Rename files with "topic" to use "subagent" terminology
Completes the topic → subagent terminology alignment by renaming
files and updating all references:
**Files renamed (5):**
- multi-topic.agent → multi-subagent.agent
- template-single-topic.agent → template-single-subagent.agent
- template-multi-topic.agent → template-multi-subagent.agent
- topic-with-actions.agent → subagent-with-actions.agent
- agent-topic-map-diagrams.md → agent-subagent-map-diagrams.md
**References updated (6 docs):**
- Updated all filename references to point to new filenames
- Updated "Topic Map" → "Subagent Map" throughout documentation
- Updated "multi-topic"/"single-topic" → "multi-subagent"/"single-subagent"
Files modified:
- README.md, SKILL.md, agent-spec-template.md
- assets/agents/README.md, assets/README-legacy.md
- references/agent-design-and-spec-creation.md
This ensures consistent "subagent" terminology across filenames,
file content, and all documentation references.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* Complete topic-to-subagent terminology update across skills
Comprehensive update replacing "topic" with "subagent" terminology throughout
the developing-agentforce and testing-agentforce skills to align with Agent
Script's `subagent` block naming.
Key changes:
- "Topic Selector" → "Subagent Router" in all agent templates and docs
- "Topic/action" → "Subagent/action" in documentation
- "Topic map" → "Subagent map" in diagram references
- Updated all architecture documentation to use "subagent" terminology
- Updated 19 .agent template files with new labels and comments
- Updated 8 reference documentation files with consistent terminology
API contract preservation:
- Test spec YAML files preserve "topic" terminology to match Testing Center API
- Added clarifying comments explaining topic/subagent equivalence in YAML files
- Field names like `expectedTopic` unchanged (Salesforce API requirement)
Preserved terms:
- "off-topic" (standard phrase for out-of-scope)
- "expectedTopic" field (Testing Center API)
- "platform topics" (Salesforce guardrail features)
32 files changed, 379 insertions(+), 366 deletions(-)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* Complete comprehensive topic-to-subagent terminology update
Thorough update replacing all remaining "topic" references with "subagent"
terminology across developing-agentforce, testing-agentforce, and
observing-agentforce skills to fully align with Agent Script's `subagent`
block naming.
Key changes:
- Agent Script syntax: @topic.<name> → @subagent.<name>
- Agent Script syntax: topic.actions → subagent.actions
- Shell script patterns: ^topic → ^subagent
- Documentation: "topic instructions" → "subagent instructions"
- observing-agentforce skill: Updated all agent architecture references
- Template files: Updated all inline comments and descriptions
- Variable names in scripts: TOPIC → SUBAGENT
Specific updates:
- 45 files changed, 294 insertions, 294 deletions
- Updated all Agent Script code examples to use @subagent syntax
- Updated observing-agentforce issue classification guide
- Updated shell script patterns in diagnostic tools
- Updated Apex comments to clarify topic field maps to subagents
Preserved (as required):
- "off-topic" and "off_topic" (standard out-of-scope phrase)
- Testing Center API fields: expectedTopic, topic: in YAML
- API response fields: .topic, generatedData.topic, topic_assertion
- STDM field names: ssot__TopicApiName__c (with clarifying docs)
- Template placeholders in test specs (API values)
- "Topic hash drift" (API field behavior)
- "Email topic/purpose" (means email subject)
- Explanatory comments about API field mapping
All Agent Script syntax and documentation now consistently uses "subagent"
while preserving backward compatibility with platform API field names.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* a few more topic -> subagent replacements
---------
Co-authored-by: Steve Hetzel <shetzel@salesforce.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
|
||
|---|---|---|
| .. | ||
| assets | ||
| references | ||
| README.md | ||
| SKILL.md | ||
Agentforce Development Skill
A Claude Code skill for building, modifying, debugging, and deploying Agentforce agents using Agent Script — Salesforce's scripting language for next-generation AI agents on the Atlas Reasoning Engine.
What This Skill Does
Agent Script was introduced in 2025 with zero training data in any AI model. This skill bridges that gap by providing structured reference material, design patterns, CLI workflows, and debugging guidance so that AI coding assistants can work with Agent Script accurately.
The skill covers the full Agent Script lifecycle:
| Domain | What It Handles |
|---|---|
| Create an Agent | Agent Spec design, environment validation, bundle generation, code authoring |
| Modify an Agent | Subagent/action changes, instruction refinement, flow control updates |
| Create or Modify Backing Logic | Invocable Apex stubs, Flow wrappers, Prompt Templates |
| Deploy and Publish | Source deploy, agent activation, publishing to channels |
| Diagnose Compilation Errors | Compiler error interpretation, syntax fixes, metadata resolution |
| Diagnose Behavioral Issues | Trace-based debugging, subagent routing, action I/O analysis |
| Diagnose Production Issues | Runtime failures, reserved keyword conflicts, deployment gotchas |
| Test an Agent | Utterance-based validation, preview with live actions, trace analysis |
| Generate Diagrams | Subagent map visualizations, agent architecture diagrams |
Skill Structure
developing-agentforce/
├── SKILL.md # Router — maps user intent to task domains and reference files
├── references/ # Domain knowledge (14 files)
│ ├── agent-script-core-language.md
│ ├── agent-design-and-spec-creation.md
│ ├── agent-validation-and-debugging.md
│ ├── salesforce-cli-for-agents.md
│ ├── agent-metadata-and-lifecycle.md
│ ├── agent-access-guide.md
│ ├── agent-user-setup.md
│ ├── actions-reference.md
│ ├── action-prompt-templates.md
│ ├── agent-subagent-map-diagrams.md
│ ├── minimal-examples.md
│ ├── known-issues.md
│ ├── production-gotchas.md
│ └── version-history.md
├── assets/ # Templates, examples, and starter agents
│ ├── agent-spec-template.md
│ ├── invocable-apex-template.cls
│ ├── bundle-meta.xml
│ ├── patterns/ # Reusable Agent Script patterns
│ ├── agents/ # Annotated example agents
│ ├── apex/ # Apex backing logic examples
│ ├── components/ # LWC components for agent channels
│ ├── metadata/ # Metadata templates
│ └── *.agent # Starter agent templates
└── staging/ # Unmerged reference material awaiting review
How It Works
SKILL.md acts as a router. It detects user intent from task descriptions, maps to a task domain, and instructs the AI assistant to read the relevant reference files before starting work. Reference files are loaded on demand — the assistant only reads what the current task requires.
Three rules apply across all domains:
- 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
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 developing-agentforce folder into your project's .claude/skills/ directory:
your-project/
└── .claude/
└── skills/
└── developing-agentforce/
├── SKILL.md
├── references/
└── assets/
Restart Claude Code after installation.
Version
Current version: 0.4.9 (2026-03-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