▋
app-dev/obsidian-vault-structure/SKILL.md

name: obsidian-vault-structure description: Build or organize an Obsidian knowledge base — Map of Content (MOC) patterns, folder conventions, wikilink discipline, YAML frontmatter for note classification, graph-view-friendly shape. Trigger when the user asks to set up an Obsidian vault, create an MOC or index note, organize notes into systems/concepts/flows, or wants to use Obsidian features (frontmatter, tags, properties, graph view) well. Do not trigger for editing Excalidraw diagrams (use obsidian-excalidraw instead) or for inspecting plugin state (use obsidian-cli).

Obsidian Vault Structure

Conventions that make a vault readable through reading view, graph view, search, and the Properties pane — without requiring Dataview or other plugins.

Baseline folder layout

Works well for technical/product knowledge bases:

VaultRoot/
├── Home.md                   # Map of Content hub
├── Systems/                  # one note per major system/product
├── Concepts/                 # cross-cutting domain concepts
├── Flows/                    # sequence/workflow notes (good for mermaid)
├── Repos/                    # per-repo granular docs (with file:line refs)
├── Diagrams/                 # Excalidraw / Canvas
└── Reference/                # external URLs, tables, lookups

No numeric prefixes on folders: Home.md is the entry point, so the file list never has to encode reading order.

Add an Assets/ folder for images, gifs, and other binaries embedded with ![[file.png]]. Keeping attachments in one place makes the "delete unused attachments" sweep tractable later.

Naming

Sentence case for folders and filenames (User interface, Build a plugin) — this matches Obsidian's own developer docs and avoids the eye-strain of long Title Case headings in the file tree. Title Case is fine if you prefer; pick one and stay consistent.

Frontmatter conventions

Frontmatter is opt-in. Add it only when a note will be grouped, queried, aliased, or visually styled — pure-prose reference pages don't need any (Obsidian's own dev docs leave most notes frontmatter-free).

Classify every note with a type: property so the Properties view groups them and search queries stay simple:

---
title: Acme Studio
type: system               # system | concept | flow | repo | reference | moc | diagram
tags:
  - acme/system
aliases:
  - Studio
related:
  - "[[Billing]]"
  - "[[Connect]]"
---
  • title: — mirror the filename or human title (useful when rendered by readers)
  • type: — controlled vocabulary so Obsidian's Properties pane can group
  • tags: — hierarchical (acme/system, acme/concept) so the tag pane nests
  • aliases: — all the names people would naturally link to
  • related: — wikilink array pointing at adjacent notes (shows in Properties, not prose)

For repo notes, also add path: (filesystem location) and stack: (array of key tech).

Visual treatment with cssclasses:

Obsidian themes ship CSS hooks you can opt into via the cssclasses: frontmatter key. Two are worth knowing about because Obsidian's own developer docs use them:

  • cssclasses: hide-title — suppresses the auto-rendered H1 above the body. Put it on Home.md (where you write your own custom landing layout) so the title doesn't double up.
  • cssclasses: reference — applies tighter, denser typography intended for lookup-style reference pages (variable tables, API listings).

Both are no-ops on themes that don't define them — they're safe to add even if you're on the default theme.

MOC (Map of Content) pattern

A Home.md that is not a dumping ground — it's a table of contents with short hooks:

---
title: Acme Knowledge Base
type: moc
---

# Acme

> [!abstract] What this vault is
> One-sentence description.

## Systems
Top-level products.
- [[Acme Studio]] — self-service UI + Lambda stack
- [[Billing]] — brand & agent lifecycle

## Concepts
Domain language.
- [[Connect Customer]]
- [[IDs and Keys]]

## Flows
Step-by-step with file:line refs.
- [[Inbound Message Flow]]
- [[Outbound Message Flow]]

## Diagrams
- [[Architecture Overview.excalidraw|Architecture Overview]]

Folder-level MOCs (one per folder) are overkill for small vaults — just use one top-level Home.md. They start earning their keep around ~10+ notes in a folder: at that size, scanning the file list is no longer pleasant and a short index note (_<Area>.md prefixed with _ so it sorts first) with grouped links + one-line hooks restores navigability. Below that threshold, Home.md alone is enough.

Wikilink discipline

  • [[Note]] resolves by name across folders. Qualify with the path only to disambiguate two notes that share a name (the conceptual Editor page vs. Reference/TypeScript API/Editor), and always add a display alias — [[Folder/Sub/Note|Display]] — so the path doesn't leak into reading view.
  • Keep ![[image.png]] embed targets in Assets/ so they're easy to audit.
  • Don't wikilink section headers in your MOC (e.g. ## [[Systems]]): clicking an unresolved header wikilink creates a stub note at vault root and clutters the graph. Use plain headings for folder-group labels.

Callouts for emphasis

Obsidian's built-in callouts render well in reading view:

> [!abstract] One-sentence summary
> ...

> [!info] Context
> ...

> [!warning] Pitfall
> ...

> [!tip] Suggested entry point
> ...

> [!note] TBD
> Stub for future expansion.

Types: abstract, note, info, tip, success, question, warning, failure, danger, bug, example, quote. Plus the - suffix for collapsed-by-default (e.g., > [!info]-).

Scope-disambiguation callout

When a note documents one variant of a broader concept (e.g., an RBM-only flow in a vault that also carries SMS / MMS / Push), open with a > [!info] Scope callout at the top of the body so readers arriving from search or the graph don't generalize incorrectly:

> [!info] Scope — RBM only
> This flow is **RBM-specific**. For SMS see [[SMS MO Flow]]; for MMS see [[MMS Flow]]. See [[Messaging Channels]] for a channel-level overview.

Pair this with a narrower title (e.g., Inbound Message Flow (RBM) rather than Inbound Message Flow) and, if useful, a frontmatter discriminator (channel: RBM) so Properties view groups variants together. This matters most when older notes predate a later broadening of scope — the callout prevents stale generalizations from surviving the rename.

Mermaid vs Excalidraw

Pick based on the task:

  • Mermaid (inline ```mermaid ... ``` fenced blocks) — flowcharts, sequence diagrams, state diagrams, ER. Auto-renders, easy to edit in-place, deterministic output. Use for flow notes and inline architecture sketches.
  • Excalidraw (see obsidian-excalidraw skill) — freeform/annotation-friendly landscape diagrams where layout matters, the user wants to drag/scribble, or there's no mermaid dialect for the shape. Heavier to author but much better for whiteboards and presentations.

Default to mermaid unless the diagram is genuinely freeform.

Pitfalls to avoid

  • Empty root stubs. If you write [[Some New Note]] in Home.md and the user clicks it before the target exists, Obsidian creates an empty Some New Note.md at vault root (default new-note location). If they later target the real note with the same name in a subfolder, they may have duplicates. Create target notes first, or configure "Default location for new notes" in Obsidian settings to a Scratch/ folder.
  • Graph view explodes when every note links to every other note. Prefer related: in frontmatter + a single ## Related section at the bottom of each note over scattering wikilinks through prose.
  • Folder-as-index notes (Systems/Systems.md) duplicate information that already lives in Home.md. Skip them unless the folder is large enough to need its own MOC.
  • Hyper-specific tags (#acme/studio/backend/api/auth/middleware) are never used again. 1-2 levels is plenty.

Periodic vault hygiene

When the user asks to audit, clean up, prune, or do a pass on the vault, work through references/maintenance-checklist.md rather than improvising. It covers orphan notes, broken links, unused attachments, stale file:line refs, and other entropy that accumulates in long-lived vaults.