agentforce-architecture-analyze

Generates architecture documentation and Mermaid diagrams from Agentforce agent design-time metadata.

Updated Jul 2, 2026
One-click install
npx skills add https://github.com/padjei/SF_Build --skill agentforce-architecture-analyze-padjei
Or copy as Structured Prompt for Agentβ–Ό
Please help me install this Agent Skill.
Skill: agentforce-architecture-analyze
Source: https://github.com/padjei/SF_Build/tree/main/.claude/skills/agentforce-architecture-analyze
Command: npx skills add https://github.com/padjei/SF_Build --skill agentforce-architecture-analyze-padjei

SYSTEM DOCUMENTATION & REQUIREMENTS

πŸ’‘ This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Understanding what an Agentforce agent actually does requires manually tracing planners, topics, actions, flows, Apex classes, and prompt templates across multiple Salesforce metadata types. This Skill automates that discovery, producing a normalized metadata tree and a human-readable architecture document in under a minute. ## Core Features & Use Cases - Declared architecture snapshot: Resolves a BotDefinition and BotVersion, then fans out parallel Tooling SOQL queries to map the planner, topics, actions, flows, Apex, prompt templates, and NGA plugins into a single normalized JSON tree. - Rendered documentation: Produces an architecture.md file with an action tree, topic anatomy, action catalog, data-flow diagram, and Mermaid invocation graphs, plus a dependency graph when unresolved references or cycles exist. - Classic ReAct and NGA support: Normalizes both planner families into one tree shape, routing NGA InvocationTargets by Salesforce ID prefix and surfacing unresolved references explicitly instead of dropping them. - Use Case: Ask to document the architecture of MyAgent in your org, and receive a metadata tree JSON plus a sectioned architecture document with Mermaid diagrams, cached for fast re-runs and diffable across versions (e.g. v3 vs v5). ## Quick Start Ask the assistant to document the architecture of your agent by providing the agent API name and your sf CLI org alias, for example: document the architecture of MyAgent in my-org-alias.

Frequently Asked Questions about agentforce-architecture-analyze

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document the architecture of an Agentforce agent?β–Ό

Provide the agent's BotDefinition DeveloperName and an authenticated sf CLI org alias. The skill resolves the active BotVersion, fetches the planner, topics, actions, flows, Apex, and prompts via parallel Tooling SOQL, and writes a metadata tree JSON plus an architecture.md with Mermaid diagrams.

How to compare two versions of a Salesforce agent?β–Ό

Run the skill once per version using the --version flag (e.g. v3 and v5). Each run produces a deterministic metadata tree JSON and architecture document under a version-specific directory, so the two outputs can be diffed directly.

Does this skill read Agentforce runtime session traces or conversation logs?β–Ό

No. It reads design-time metadata only: BotDefinition, GenAiPlanner, GenAiPlugin, GenAiFunction, Flow, ApexClass, and GenAiPromptTemplate objects. Runtime audit rows, session traces, and generation timings are explicitly out of scope.

What prerequisites are needed to run Agentforce architecture analysis?β–Ό

You need the sf CLI authenticated against the target org (via sf org login web --alias) and Python 3.10 or later. The skill shells out to sf org display for the access token and uses only Python standard library modules.

Why does the architecture output show unresolved references?β–Ό

Unresolved entries appear when an InvocationTarget has an unknown Salesforce ID prefix, a SOQL channel fails, or a describe field is missing. They are listed in the tree's _unresolved array with a reason string, and the run status becomes PARTIAL_OK rather than failing silently.

How long does an Agentforce architecture snapshot take?β–Ό

Typical runs take 30-45 seconds with a 60-second cap on reference fixtures, thanks to a parallel Tooling SOQL fan-out that is 3-5x faster than sequential Metadata API retrieves. Cached trees return almost instantly unless --force is passed.