arch-mmd_skill

Overview

This skill creates or updates an ARCHITECTURE.mmd Mermaid diagram that maps a codebase or product at a high level. It produces a single-screen, readable architecture overview focused on the main components, data flow, and external dependencies. Use it to keep the repository's architecture diagram current after changes or when someone asks to see the system layout.

How this skill works

The skill scans the project to identify project type, entry point(s), 5–15 core modules, primary data flow, key external services, and major boundaries (client/server, packages). It then generates a Mermaid diagram using graph TD, concise node labels with <br/> for line breaks, short uppercase node IDs, minimal edges, and color-coded styles. If an ARCHITECTURE.mmd already exists, it reads and updates the file rather than recreating it, preserving prior structure unless it is clearly outdated.

When to use it

• When a reviewer or teammate asks for a high-level architecture overview.
• After major refactors, new services, or boundary changes that affect system layout.
• Before onboarding new contributors to give them a quick mental model.
• When preparing documentation or release notes that reference system components.

Best practices

• Target 8–20 nodes; fewer is usually better to preserve readability.
• Use graph TD (top-down) by default and graph LR only for pipeline-shaped flows.
• Avoid subgraphs; use a small color palette (4–6 colors) and style nodes for grouping.
• Label nodes with file/module name and a 1–2 line description using <br/>.
• Show primary flows only; avoid exhaustive connections or every function call.
• Read and update existing ARCHITECTURE.mmd instead of discarding prior diagrams.

Example use cases

• Generate an ARCHITECTURE.mmd for a small web app showing UI, API gateway, core service, and database.
• Update the diagram after splitting a monolith into a new worker service and external queue.
• Produce a quick diagram for an internal demo to illustrate how requests flow from client to storage.
• Create a readable overview for a monorepo by collapsing package groups into single nodes.