# Architect Diagram

> Use when the user asks for a diagram of a system, integration, flow, state, data model, or deployment topology. Triggers on "show me", "draw", "diagram of", or artifact-shaped nouns like "sequence", "C4 Container view", "state machine". Produces Mermaid diagrams (flowchart, sequenceDiagram, C4, stateDiagram-v2, erDiagram) routed by intent. Cloud-aware (AWS, Azure, GCP, and primitives providers li…

- **Type:** Skill
- **Install:** `agentstack add skill-eugenelim-agent-ready-repo-architect-diagram`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [eugenelim](https://agentstack.voostack.com/s/eugenelim)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [eugenelim](https://github.com/eugenelim)
- **Source:** https://github.com/eugenelim/agent-ready-repo/tree/main/packs/architect/.apm/skills/architect-diagram

## Install

```sh
agentstack add skill-eugenelim-agent-ready-repo-architect-diagram
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill: architect-diagram

Produce Mermaid diagrams that survive enterprise wiki rendering and stay
readable at a glance. Structural discipline (boundaries, technology labels,
trust zones) beats pretty.

## Mode detection — pick one at entry

Read the user's message and route once. Don't ask the user to flag intent.

| Signal | Mode |
| --- | --- |
| Vague idea, no code or paths in scope. "Draw me how a checkout flow could look." | **design** |
| Repo path, file list, or "the system as it is today" in scope. | **document** |
| Diagram pasted into the conversation + "is this ok / what's wrong". | **review** |
| Existing diagram + a diff request ("add a caching layer", "remove X"). | **update** |

If two modes plausibly fit, ask once which the user wants.

- **design** — generate from the user's words. Fabricate component
  names only where the user hasn't named one; flag fabrications.
- **document** — read the code or paths first; only diagram what is
  actually there. Never invent names.
- **review** — quick rubric pass against `references/diagram-rubric.md`;
  if the user wants severity-tagged findings, route to the
  `architect-review` skill (if installed) for the full critique.
- **update** — apply the requested diff. Surface side-effects the user
  didn't ask for (orphaned nodes, broken trust boundaries).

## Procedure

1. **Route by mode** (above). For *document* mode, read before drawing.

2. **In document or update mode — extend "read the repo" to "read the
   landscape."** *Only* in these two modes, and *only* when the as-is system
   integrates **beyond the repo boundary** and an *internal* knowledge-retrieval
   surface is reachable this session (an enterprise-knowledge MCP tool, an
   internal CLI, an in-repo doc set — public web does **not** count), load
   `references/knowledge-surfaces.md` and consult the descriptive current-system
   facets (current landscape, interfaces, operational reality) to ground the
   beyond-repo boxes, arrows, and edge labels. **Name what you drew from** (the
   surface, or "repo only / none"). A node or edge you can't ground stays
   `` or becomes a question — never a guess (this strengthens the
   never-fabricate-names rule below); a surface-derived edge the repo
   contradicts is **flagged**, not silently drawn over. This step does **not**
   apply in **design** mode (you're drawing the user's hypothetical —
   fabrication is allowed-but-flagged) or **review** mode (route to
   `architect-review`).

3. **Pick the notation from intent.** Always load
   `references/notation-routing.md` — it carries the intent → notation
   decision table, the split-when-too-big rule, and the *don't draw*
   cases (comparison, checklist, two-component flow).

4. **Load the syntax reference for the chosen notation** —
   `references/mermaid-{flowchart,sequence,c4,state,er}.md`, one file
   per notation, on demand. For C4 Container drafts, the starter
   shape is in `assets/c4-container.mmd`.

5. **Load cross-cloud patterns for any cloud-aware diagram.** Load
   `references/cloud-patterns.md` whenever the diagram crosses cloud
   boundaries — boundary stack, public-vs-private subnets, async vs.
   sync edges, trust-boundary labeling, storage shapes. Then layer
   the vendor-specific reference:

   - **Any AWS / Azure / GCP service — or a primitives provider
     (Hetzner and its class)** → load `references/cloud-.md`
     (incl. `cloud-primitives.md`) for boundary vocabulary, subgraph
     nesting, and gotchas. Multi-cloud → load multiple references.
   - **Agentic platform named** → load
     `references/agentic-.md` (`bedrock-agentcore`,
     `ai-foundry`, `vertex-agent-engine`). A diagram of AgentCore is
     *not* "AWS with a Lambda in it".

6. **Draft the diagram inline.** Default to `flowchart TB` with
   subgraph nesting and emoji or text markers — renders cleanly in
   GitHub, Confluence, Azure DevOps Wiki, and GitLab. Only if the
   user's target renderer is known to support it, mention Mermaid's
   newer `architecture-beta` syntax as an alternative — load
   `references/mermaid-architecture-beta.md` for the trade-offs and
   skeleton before offering. Do not default to it; rendering is
   inconsistent across enterprise wikis. **When the diagram
   distinguishes more than one category of thing or relationship, load
   `references/visual-encoding.md`** — map each visual channel (shape,
   grouping, position, edge style, marker) to meaning by data type, and
   keep colour as reinforcement only, never the sole carrier.

7. **Self-check against `references/diagram-rubric.md`.** Fix
   violations before showing the user. The non-negotiables: every
   Container has a technology label; no bare relation labels; fits
   one screen (≤15 nodes); document mode never fabricates names;
   trust boundaries are visible (dashed subgraph border or explicit
   comment).

8. **Offer to save.** Scan for an obvious home (`docs/architecture/`,
   `diagrams/`, `docs/`). Suggest a kebab-case `.mmd` filename.
   Saving is an offer, never automatic.

## Anti-patterns to refuse

- **Drawing without naming the trust boundary.** A cross-account or
  cross-tenant arrow without a labeled boundary is a security hazard
  rendered as art. Add the boundary, then draw.
- **Picking the notation the user named when the intent disagrees.**
  If the user asks for a "sequence diagram" of *what talks to what*,
  the right answer is a Container view. Push back; offer both.
- **Defaulting to `architecture-beta` because it looks nicer.**
  Enterprise wikis render flowchart consistently; architecture-beta
  is uneven. Mention it as an option, not the default.
- **Fabricating service or component names in document mode.** Read
  the code; if a name isn't there, mark the node `` or ask.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [eugenelim](https://github.com/eugenelim)
- **Source:** [eugenelim/agent-ready-repo](https://github.com/eugenelim/agent-ready-repo)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-eugenelim-agent-ready-repo-architect-diagram
- Seller: https://agentstack.voostack.com/s/eugenelim
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.