| created | "2026-04-17T00:00:00.000Z" |
| modified | "2026-06-28T00:00:00.000Z" |
| reviewed | "2026-06-28T00:00:00.000Z" |
| name | vault-mocs |
| description | Map-of-Content (MOC) curation for Obsidian vaults. Use when creating a MOC for a tag, extending with orphans, fixing legacy MOC tags, or analyzing coverage. |
| user-invocable | false |
| allowed-tools | Read, Edit, Write, Grep, Glob |
MOC Curation
When to Use This Skill
| Use this skill when... | Use the alternative instead when... |
|---|
| Creating or extending a Map of Content hub for a tag category | Reconnecting individual orphaned notes without building a hub — use vault-orphans |
Migrating legacy 🗺️ MOC tags to canonical 📝/moc | Renaming or consolidating non-MOC tags across the vault — use vault-tags |
| Auditing MOC coverage and linking orphans into existing hubs | Repairing broken [[...]] references inside an existing MOC — use vault-wikilinks |
A Map of Content (MOC) is a structured hub note that organizes related content via wikilinks. It's the primary navigation surface of a mature Obsidian vault — more useful than tags, more discoverable than search.
Canonical MOC Shape
---
tags: [📝/moc]
---
# Neovim MOC
Central hub for Neovim configuration, plugins, and workflows.
## Core
- [[Neovim]] — base configuration
- [[Lazy.nvim]] — plugin management
## Plugins
- [[nvim-treesitter]]
- [[Mason LSP]]
## Keybindings and Workflow
- [[Neovim Keybindings]]
- [[Neovim Session Management]]
Rules:
- Tag is exactly
📝/moc — not 🗺️ (legacy), not MOC (flat), not 📝/MOC (wrong case).
- File lives in
Zettelkasten/ (personal) or work/MOC/ (work).
- Filename is
{Subject} MOC.md — suffix, not prefix.
- Body has a one-paragraph description, then
## section headings, then bullet-list wikilinks.
- Never has
id: or other legacy frontmatter.
Legacy MOC Fixups
| Issue | Fix |
|---|
tags: 🗺️ | Rewrite to tags: [📝/moc] |
tags: [🗺, 📝/moc] | Deduplicate to tags: [📝/moc] |
MOC in work/z/ instead of work/MOC/ | Move file |
Uses [[Kanban/Foo]] path-qualified links | Rewrite to [[Foo]] when basename unique |
Coverage Analysis
For each tag category (🛠️/, 🔌/, 💻/, etc.), the vault-agent mocs.analyze_mocs analyzer reports how many tagged notes are NOT linked from any MOC. High uncovered counts indicate:
- Missing MOC — the category has 10+ notes but no MOC exists.
- Stale MOC — the MOC exists but hasn't been updated with recent additions.
- Tag mismatch — notes are tagged but don't belong in the relevant MOC.
Offline Fallback (App Closed)
The detection methodology above is unchanged — only the data source changes when Obsidian (and its obsidian CLI / live link index) is closed. The obsidian CLI and vault-agent analyzers are the live-index path; parsing the .md corpus directly with Glob/Grep is the deterministic headless default, and for batch/scheduled audits it is often the better choice (reproducible, free of app/index state). vault-frontmatter already operates this way.
Parse the corpus directly:
- Frontmatter — read each note's YAML block between the leading
--- fences; extract tags, aliases, context. See vault-frontmatter for YAML-block mechanics.
- Wikilinks — match
[[Target]], [[Target|Alias]], [[Target#Heading]], [[folder/Target]], and ![[embed]]. Resolve each target to a note by basename, then relative path, then alias (from frontmatter), all case-insensitive. Resolve ![[embed]] against attachments as well as notes — the attachment folder is per-vault configurable, so read it from .obsidian/app.json (attachmentFolderPath) and fall back to the vault root / Files/ only when that key is unset.
Coverage analysis offline: for each tag category, count notes whose parsed frontmatter tags place them in the category but which no 📝/moc-tagged note links to (via the resolution cascade). That is the same uncovered count mocs.analyze_mocs produces from the live index.
Creating a New MOC
Thresholds (heuristic):
- ≥ 10 tagged notes in the category AND
- No existing MOC covers them AND
- Notes share enough subject to belong in one hub
If all three hold, create Zettelkasten/{Category} MOC.md:
---
tags: [📝/moc]
---
# {Category} MOC
{One-paragraph framing of the category.}
## {Section}
- [[Note1]]
- [[Note2]]
Pick 2–4 ## sections that reflect natural groupings within the notes — don't force a deep hierarchy.
Extending an Existing MOC
When the analyzer reports orphaned notes that belong in an existing MOC:
- Read the MOC and find the most appropriate
## section (or create a new one if 3+ notes fit a new grouping).
- Add wikilinks one per bullet, alphabetical within the section.
- Keep descriptions brief — one short phrase per link at most.
Don't add a "See also" or "Random" section as a dumping ground. If a note doesn't fit any section, reconsider whether it belongs in this MOC at all.
Never Do
- Don't create nested MOCs (MOC of MOCs) unless the vault has 20+ MOCs that justify a top-level index.
- Don't dataview-generate MOC content in place of hand-curated links. Dataview is fine for supplementary sections ("Recent notes in this category"), but the primary content should be hand-picked.
- Don't add the
📝/moc tag to a note that isn't actually a MOC — it pollutes MOC inventories.
- Don't rename existing MOCs without updating every link (use
vault-wikilinks rewrite patterns).
Commit Messages
| Action | Commit |
|---|
| New MOC | feat(mocs): add {Category} MOC covering N notes |
| Fixup tag | fix(mocs): 🗺️ → 📝/moc on work MOCs |
| Add orphans | feat(mocs): link 12 notes into Neovim MOC |
| Rewrite path-qualified link | fix(mocs): unqualify [[Kanban/X]] → [[X]] across 6 MOCs |
Safety
- Never modify a MOC's section structure without the user's input — they reflect the user's mental model.
- When adding links, preserve the user's existing sort order (alphabetical, chronological, by-importance — look at the first section to infer).
- Don't link notes that are tagged but clearly off-topic for the MOC.
Related Skills
- vault-orphans — identifies candidate notes to add to MOCs
- vault-tags — tag taxonomy that drives coverage analysis
- vault-wikilinks — link syntax and safe-rewrite rules
