# Docs Diagram

> Generate a Mermaid diagram (ER, architecture, deployment, or security)

- **Type:** Skill
- **Install:** `agentstack add skill-mgiovani-cc-arsenal-docs-diagram`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mgiovani](https://agentstack.voostack.com/s/mgiovani)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mgiovani](https://github.com/mgiovani)
- **Source:** https://github.com/mgiovani/cc-arsenal/tree/main/skills/docs-diagram

## Install

```sh
agentstack add skill-mgiovani-cc-arsenal-docs-diagram
```

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

## About

# Generate System Diagrams

Generate a Mermaid diagram — ER, architecture, deployment, or security — from the
real codebase and write it to `docs/`.

## Supported Diagram Types

| Type | Output File | Description |
|------|------------|-------------|
| `er` | `docs/data-model.md` | Entity-Relationship diagram from database models |
| `arch` | `docs/architecture.md` | System architecture and component relationships |
| `deployment` | `docs/deployment.md` | Deployment infrastructure and CI/CD |
| `security` | `docs/security.md` | Security architecture and data flow |

## Workflow

### 1. Parse the request

Extract the diagram type (`er`, `arch`, `deployment`, `security`) and any optional
scope context (e.g. "for the user and order tables"). If the type is missing or
invalid, don't guess — stop, and end your response with a direct question naming
the supported types, e.g. "Which diagram type do you want: architecture, er,
deployment, or security?". Listing the types without asking, or asking without
listing them, is not enough — go no further until the user answers.

### 2. Analyze the codebase

- **Scoped request** (e.g. "er diagram for the user and order tables"): Read/Grep
  the named files directly.
- **Broad or ambiguous request** (e.g. "show me the architecture" on an unfamiliar
  codebase): when a Task tool is available, spawn one Explore subagent per aspect
  that matters for the diagram type (e.g. for `arch`: services, databases,
  external integrations, data flow). Without a Task tool, run the same per-aspect
  checks sequentially inline with Read/Grep/Glob instead — same checks, no
  parallelism, just slower.

See [references/detection-patterns.md](references/detection-patterns.md) for
detection commands per diagram type.

### 3. Verify before adding anything

Diagrams must represent real, existing components — never a plausible guess.

- Read the file that defines a component before adding it; don't add it from
  memory or inference.
- Confirm a relationship by finding the actual import/reference/FK in code, not
  by assuming two similarly-named things are connected.
- Get counts by running a command (e.g. `find . -name "*service*" | wc -l`), then
  use that number — never estimate "about 5 services".
- Drop anything that can't be verified this way. An empty directory or an unused
  stub file is not a component.

### 4. Generate the Mermaid diagram

Use the syntax for the diagram type from
[references/mermaid-patterns.md](references/mermaid-patterns.md). Keep it
readable — if a system has too many pieces for one clear diagram, split it into
multiple focused views rather than cramming everything into one.

### 5. Populate the template

Load `assets/templates/.md` (`er` → `data-model.md`, `arch` →
`architecture.md`, `deployment` → `deployment.md`, `security` → `security.md`).
Replace `{{PROJECT_NAME}}`, `{{DATE}}`, the diagram placeholder, and the
entity/component list placeholders with the verified content from steps 3-4.

### 6. Write the output

Write to the file in `docs/` named in the table above. If it already exists, ask
before overwriting, and preserve any hand-written sections you can identify
(anything outside the placeholder fields).

### 7. Report results

State the diagram type, the output file, and the actual counts detected (e.g.
"4 entities, 6 relationships") — these must be the numbers from step 3's
commands, not a summary written from memory. Suggest regenerating when the
diagrammed subsystem changes.

## Worked Examples

**Scoped ER request** — `docs-diagram er for the user and order tables`: Grep for
`class User` / `class Order` in the ORM models directory, read both files, extract
columns and FKs, confirm the `Order.user_id` FK by checking it's actually declared
in the model, then write `docs/data-model.md` with an `erDiagram` block containing
only `USER` and `ORDER`.

**Broad architecture request** — `docs-diagram arch`: with a Task tool, spawn
Explore agents for services, databases, and external integrations; without one,
run `find . -name "*service*"`, `find . -name "*.config.*"`, and a grep for known
client SDKs sequentially. Merge only the components every check confirms into one
`graph TB` diagram.

**Missing/invalid type** — `docs-diagram`: do not guess a type or generate
anything; end the response with "Which diagram type do you want: architecture,
er, deployment, or security?" alongside their output files.

## Notes

- Regenerate after the diagrammed subsystem changes (schema migration, new
  service, new deploy target, new auth flow) — this skill is meant to be re-run,
  not written once and left stale.
- Additional context on codebase detection commands and Mermaid syntax lives in
  [references/detection-patterns.md](references/detection-patterns.md) and
  [references/mermaid-patterns.md](references/mermaid-patterns.md) — load them
  when doing the actual detection/generation work, not before.

## Source & license

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

- **Author:** [mgiovani](https://github.com/mgiovani)
- **Source:** [mgiovani/cc-arsenal](https://github.com/mgiovani/cc-arsenal)
- **License:** MIT

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-mgiovani-cc-arsenal-docs-diagram
- Seller: https://agentstack.voostack.com/s/mgiovani
- 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%.