description: "Salesforce architecture diagrams using Mermaid with ASCII fallback. Use this skill when generating text-based diagrams for Salesforce architecture, OAuth flows, ERDs, integration sequences, or Agentforce structure. TRIGGER when: user says \"diagram\", \"visualize\", \"ERD\", or asks for sequence diagrams, flowcharts, class diagrams, or architecture visualizations in Mermaid. DO NOT TRIGGER when: user asks about non-Salesforce systems."
Use this skill when the user needs **text-based diagrams**: Mermaid diagrams for architecture, OAuth, integration flows, ERDs, or Agentforce structure, plus ASCII fallback when plain-text compatibility matters.
## Scope
### In Scope
Use `external-diagram-mermaid-generate` when the user wants:
- Mermaid output
- ASCII fallback diagrams
- architecture, sequence, flowchart, or ERD views in markdown-friendly form
- diagrams that can live directly in docs, READMEs, or issues
### Out of Scope — Delegate elsewhere when the user wants:
- non-Salesforce systems only → use a more general diagramming skill
- object discovery before an ERD → [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md) or [platform-custom-field-generate](../platform-custom-field-generate/SKILL.md)
- output preference: Mermaid only, ASCII only, or both
- whether styling should be minimal, documentation-first, or presentation-friendly
- for ERDs: whether org metadata is available for grounding
---
## Recommended Workflow
### 1. Pick the right diagram structure
- use `sequenceDiagram` for time-ordered interactions
- use `flowchart LR` for ERDs and capability maps
- keep a single primary story per diagram when possible
### 2. Gather data
For ERDs and grounded diagrams:
- use [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md) or [platform-custom-field-generate](../platform-custom-field-generate/SKILL.md) when real schema discovery is needed
- optionally use the local metadata helper script for counts / relationship context when appropriate
### 3. Generate Mermaid first
Apply:
- accurate labels
- simple readable node text
- consistent relationship notation
- restrained styling that renders cleanly in markdown viewers
### 4. Add ASCII fallback when useful
Provide an ASCII version when the user wants terminal compatibility or plaintext documentation.
### 5. Explain the diagram briefly
Call out the key relationships, flow direction, and any assumptions.
---
## High-Signal Rules
### For sequence diagrams
- use `autonumber` when step order matters
- distinguish requests vs responses clearly
- use notes sparingly for protocol detail
### For ERDs
- prefer `flowchart LR`
- keep object cards simple
- use clear relationship arrows
- avoid field overload unless the user explicitly asks for field-level detail
- color-code object types only when it improves readability
### For ASCII output
- keep width reasonable
- align arrows and boxes consistently
- optimize for readability over decoration
---
## Output Format
````markdown
## <Diagram Title>
### Mermaid Diagram
```mermaid
<diagram>
```
### ASCII Fallback
```text
<ascii>
```
### Notes
-<keypoint>
-<assumptionorlimitation>
````
---
## Cross-Skill Integration
| Need | Delegate to | Reason |
|---|---|---|
| real object / field definitions | [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md) / [platform-custom-field-generate](../platform-custom-field-generate/SKILL.md) | grounded ERD generation |
| Mermaid renderer not available | Provide ASCII fallback automatically; note that the Mermaid block still carries the diagram for copy-paste into a renderer |
| ERD becomes unreadable with too many objects | Split into sub-diagrams by domain (Sales, Service, etc.) and link them in prose |
| Sequence diagram step order unclear | Use `autonumber` directive to make step ordering explicit |
| OAuth flow actors differ by grant type | Read the relevant asset template first before generating to avoid actor mismatch |
---
## Reference File Index
### Conventions & rules — read before generating
- [references/diagram-conventions.md](references/diagram-conventions.md) — consistency rules for all diagram types
