docs-diagram

Files (9)

• SKILL.md
• architecture.md · assets/templates/
• data-model.md · assets/templates/
• deployment.md · assets/templates/
• security.md · assets/templates/
• evals.json · evals/
• trigger-eval.json · evals/
• detection-patterns.md · references/
• mermaid-patterns.md · references/

SKILL.md (first lines)

# 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/<type>.md` (`er` → `data-model.md`, `arch` →
`architecture.md`, `deployment` → `deployment.md`, `security` → `security.md`).
Replace `{{PROJECT_NAME}}` and `{{DATE}}`, plus 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. Validate the diagram renders

Needs `mmdc`: install with `npm i -g @mermaid-js/mermaid-cli`, or run it ad hoc by defining `mmdc() { npx -y -p @mermaid-js/mermaid-cli mmdc "$@"; }` first. If Chromium refuses to launch in a sandbox, add `-p` with a puppeteer config of `{"args":["--no-sandbox"]}`.

Run this on the file you wrote; each `FAIL <name>-N.mmd` names the doc and the Nth mermaid block in it:

```bash
d=$(mktemp -d)
for md in docs/<file>.md; do
  awk -v out="$d/${md//\//__}" '/^```mermaid/{f=out "-" ++n ".mmd"; next} /^```/{f=""} f{print > f}' "$md"
done
for f in "$d"/*.mmd; do mmdc -q -i "$f" -o "${f%.mmd}.svg" || echo "FAIL $f"; done
```

Fix each failing block using its parser error, then re-run until nothing prints `FAIL`. Cap at 3 rounds, then report the blocks that still fail. An unreplaced `{{PLACEHOLDER}}` in a block also fails here. If `mmdc` can't be installed (no Node or no network), say so in the report and fall back to a careful syntax review against [references/mermaid-patterns.md](references/mermaid-patterns.md).

### 8. Report results

State the diagram type and the output file, then report 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, check the `Order.user_id` FK is 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

From mgiovani/cc-arsenal, MIT.

More from mgiovani/cc-arsenal