omm-scan
Scan codebase architecture and generate/update .omm/ documentation
Install / Use
npx skills add oh-my-mermaid/oh-my-mermaid --skill omm-scanInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of omm-scan
omm-scan scores 86/100 on our quality scale, 685th of 1,153 Content & Media skills we index.
Its SKILL.md is 7.1 KB long, well organised into 15 sections with 4 code examples: a thorough specification that gives an agent plenty to work with.
With 3,378 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 7 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-04 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 94/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-10-01. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
omm-scan compared with similar skills
All 4 of these similar skills score higher than omm-scan; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| omm-scan (this skill)by oh-my-mermaid | 86 | 3.4k | 7mo ago | SKILL.md |
| siyuanby siyuan-note | 100 | 47.3k | today | MCP Server |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
Frequently asked questions
- How do I install omm-scan?
- Run
npx skills add oh-my-mermaid/oh-my-mermaid --skill omm-scan. The install tabs above show the steps for each supported agent. - Which AI agents does omm-scan work with?
- It is written for Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is omm-scan safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 94/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is omm-scan still maintained?
- The repository was last updated about 7 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: omm-scan description: Scan codebase architecture and generate/update .omm/ documentation. Use when the user says "omm scan", "scan architecture", "update architecture", "refresh diagrams".
omm-scan — Perspective-Based Architecture Scanner
Purpose
Analyze the codebase and generate .omm/ architecture documentation using perspective-driven recursive analysis.
- A perspective is a top-level element — a distinct way to look at the architecture.
- Each element in a diagram gets analyzed recursively. If it has internal structure, it becomes a child element (subdirectory with its own diagram). If not, it stays a leaf.
- The filesystem determines nesting. Element IDs in diagrams match child directory names. The viewer resolves groups from the filesystem.
Prerequisites
command -v omm || npm install -g oh-my-mermaid
If the install fails, tell the user: "Please run npm install -g oh-my-mermaid in your terminal, then try again."
Step 0: Check Language
omm config language
Write field content (description, context, constraint, concern, todo, note) in the configured language. Default is English. Element IDs, directory names, and diagram node IDs are always English kebab-case.
Step 1: Explore the Codebase
Use Glob and Read to understand the project:
- Read
package.json,pyproject.toml, or equivalent manifests - List top-level directories to identify module boundaries
- Read key entry points (main, index, app files)
- Look for route definitions, service layers, database connections, external integrations
Step 2: Select Perspectives
From the catalog below, choose which perspectives are meaningful for this codebase.
Perspective Catalog
| Perspective | When to create | What it answers |
| --- | --- | --- |
| overall-architecture | Always | What exists and how pieces relate |
| request-lifecycle | Any server/API | How a request enters and gets handled end-to-end |
| data-flow | Any data processing, DB usage | Where data comes from, transforms, and lands |
| dependency-map | Complex module graph | What depends on what, what's shared |
| external-integrations | External APIs/services | What the system connects to and why |
| state-transitions | Stateful features (frontend or backend) | How state changes and what triggers it |
| route-page-map | Frontend with routing | Page structure and navigation flow |
| command-surface | CLI tools | Command hierarchy and dispatch |
| extension-points | Plugin/extension systems | Extension architecture and registry |
| pipeline | ML/data pipelines | Stage topology and data flow |
| orchestration | Event-driven/queue systems | Publisher, subscriber, broker topology |
| storage | 2+ storage systems | Storage topology (DB, cache, queue, object store) |
Don't force perspectives that don't exist in the code.
Step 3: Generate Perspectives with Recursive Drill-Down
For each selected perspective, follow this recursive process:
3a. Write the perspective diagram
Element IDs match child directory names. The viewer resolves nesting from the filesystem.
omm write <perspective> diagram - <<'MERMAID'
graph LR
renderer["Renderer\nsrc/renderer/"]
renderer -->|"IPC invoke/on"| main-process["Main Process\nsrc/main/"]
main-process -->|"spawn PTY"| engine-system["Engine System\nsrc/main/engine/"]
main-process -->|"read/write JSON"| data-store["Data Store\nsrc/main/store.ts"]
main-process -->|"xterm.js"| terminal-dock["Terminal Dock\nsrc/renderer/src/panel/"]
MERMAID
3b. Write the other 6 fields
Each as a separate omm write command: description, context, constraint, concern, todo, note.
3c. Recursive drill-down: analyze every element
For every element in the diagram:
-
Analyze the code it represents (Glob + Read the relevant files/directories)
-
Write description for every node — no exceptions. This creates the element directory. Optionally write other fields (context, constraint, concern, todo, note) if relevant — Write in the configured language.
omm write <perspective>/<element-name> description - <<'EOF' (what this element does, which files/dirs it covers) EOF -
Decide leaf or group:
- Distinct internal components found → write a diagram and recurse deeper (it becomes a group)
- No meaningful sub-components (single file, trivial wrapper, external system) → write remaining fields only (it stays a leaf)
-
If group — write diagram and recurse:
omm write <perspective>/<element-name> diagram - <<'MERMAID' graph LR (internal elements) MERMAIDThen repeat step 3c for each element in this diagram.
Example recursion
overall-architecture (perspective)
elements: renderer, main-process, engine-system, data-store, terminal-dock
→ analyze renderer (src/renderer/)
→ finds: App.tsx, components/, hooks/, stores/, world/
→ group → write diagram with: components, stores, world
→ analyze components → 15 .tsx files, no sub-structure → leaf
→ analyze stores → 4 zustand stores → leaf
→ analyze world → OfficeCanvas + PixiJS logic → leaf
→ analyze main-process (src/main/)
→ finds: ipc.ts, auth/, engine/, terminal-session-service.ts, store.ts
→ group → write diagram with: auth, engine, terminal-session
→ analyze auth → auth-service.ts, callback-server.ts → leaf
→ analyze engine → claude-code.ts, codex.ts → leaf
→ analyze data-store (src/main/store.ts)
→ single file → leaf
→ analyze terminal-dock (src/renderer/src/panel/)
→ TerminalDock.tsx, DockManager → leaf
Step 4: Summarize
Report what was created/updated and suggest omm view to view.
Diagram Rules
-
Element IDs must match the child directory name. Use kebab-case:
main-process,data-store,terminal-dock. -
Element labels use two-line format: name + file path, separated by
\n:main-process["Main Process\nsrc/main/"] auth-service["Auth Service\nsrc/auth/service.ts"] -
Every edge must have a meaningful label:
A -->|"why this connection exists"| B -
More elements in one diagram means you should recurse deeper.
-
Use
graph LRfor most diagrams,graph TDfor hierarchies. -
Use
classDeffor visual distinction when helpful:| Style | Color | When to use | | --- | --- | --- | |
external|#585b70| Third-party services outside your codebase | |concern|#f38ba8| Known risk or bottleneck | |entry|#89b4fa| Entry points (HTTP handler, CLI, queue consumer) | |store|#a6e3a1| Persistent storage (DB, cache, file system) |classDef external fill:#585b70,stroke:#585b70,color:#cdd6f4 classDef concern fill:#f38ba8,stroke:#f38ba8,color:#1e1e2e classDef entry fill:#89b4fa,stroke:#89b4fa,color:#1e1e2e classDef store fill:#a6e3a1,stroke:#a6e3a1,color:#1e1e2e
General Rules
- Write each field as a separate
omm writecommand. Eachomm writemust be its own Bash tool call. - Do not rewrite elements that haven't changed.
- Do not create circular references. A child element must never reference its parent.
Related Skills
siyuan
47.3kAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
