obsidian-organizer

Obsidian Organizer

Keep a large Obsidian vault tidy over time by (1) filing new notes into the best-fit folder and (2) auditing/reorganizing existing structure. Both modes lean on one shared idea: a plain-markdown map of "what goes where" that lives inside the vault so it never drifts out of sync with reality.

This skill drives the obsidian CLI (from the separate obsidian-cli skill), which talks to the live, running Obsidian desktop app. The app must be open. If a command fails with a connection/vault error, tell the user to open Obsidian rather than guessing.

Why the map lives in the vault (read this first)

Deciding a folder for every new note by re-listing ~650 folders is expensive and guesses drift. Copying the folder taxonomy into Claude's private memory creates a worse problem: a stale copy that silently disagrees with the real vault.

The fix is one file, 00_Index/Folder_Map.md, checked into the vault itself. It is the single source of truth for filing decisions. Read it with one cheap call before you file or reorganize — do not re-run a full obsidian folders traversal unless the map is missing or the user asks you to rebuild it.

obsidian read path="00_Index/Folder_Map.md"

It is deliberately plain markdown (headers + bullets, no required frontmatter) so both you and the human can append to it by hand as new categories emerge. When you create a new folder/category, add a line to this file so the next filing decision remembers it.

If the map does not exist (deleted, or a fresh vault), rebuild it from the live vault, not from a copy stashed in this skill — a bundled copy would drift from reality, which is the whole failure this file exists to prevent. List the real structure with obsidian vault="MyVault" folders (and folders folder=... for depth), draft a plain-markdown map grouped by top-level PARA folder with a short "what goes here" note per folder plus a filing rule-of-thumb, confirm the groupings with the user, then create it: obsidian vault="MyVault" create path="00_Index/Folder_Map.md" content="...".

Vault targeting

MyVault above is a placeholder — substitute the user's actual vault name everywhere. If the user has more than one vault, target the intended one explicitly on every command so a stray "most recently focused vault" default cannot misfile a note:

obsidian vault="MyVault" read path="00_Index/Folder_Map.md"

vault= must be the first parameter. This is the only vault-specific value in the skill — everything else comes from the vault's own Folder_Map.md.

The one hard safety rule: never touch vault files with raw shell

When you relocate or rename a file, always use the CLI's own move / rename commands. These go through Obsidian's API, so Obsidian's built-in "automatically update internal links" behavior rewrites every wikilink and backlink across the vault to follow the moved file. A raw mv, rm, rmdir, or find -delete on a path inside the vault skips that repair and silently leaves broken links pointing at the old location.

So, for anything under the vault directory:

• Move/rename → obsidian move ... or obsidian rename ...
• Delete → obsidian delete ... (sends to trash unless permanent)
• Never use Bash mv / rm / rmdir / find -delete on vault-internal paths.

Reading a file's bytes with a non-mutating tool is fine; mutating vault files is CLI-only.

---

Mode 1 — File a note

Goal: given a note (an existing path, or a title + content you're about to write), put it in the single best-fit folder.

1. Read the map once: obsidian vault="MyVault" read path="00_Index/Folder_Map.md".
2. Match the note's topic to a destination using the map's filing rules. Favor an existing specific subfolder over a general one (e.g. a Seurat how-to goes to 03_Research_Knowledge/Bioinformatics/seurat/, not a generic bucket).
3. Act on the best fit:
   • A clearly matching folder exists → file it there.
     • New note: obsidian vault="MyVault" create path="03_Research_Knowledge/Bioinformatics/seurat/My Note.md" content="..." silent
     • Existing note to relocate: obsidian vault="MyVault" move path="00_Inbox/My Note.md" to="03_Research_Knowledge/Bioinformatics/seurat" (to may be a folder or a full path).
   • A rough-but-imperfect fit exists (e.g. a tool with no dedicated subfolder) → use the map's catch-all convention (e.g. Bioinformatics/misc/) and tell the user where it went.
   • No category fits well → stop and ask the user before inventing a folder. Propose a name and location; don't silently create new taxonomy.
4. Remember new categories. When the user approves a new folder, append a line describing it under the right section of 00_Index/Folder_Map.md (obsidian append path="00_Index/Folder_Map.md" content="...") so future filing decisions know about it.
5. Briefly report the final path.

Notes on the CLI: create makes intermediate folders as needed; add silent so it doesn't steal focus by opening the note. move's to accepts a destination folder or a full path; use rename name="New Title" to change a title in place.

---

Mode 2 — Audit / reorganize

Goal: given a scope (a folder path, "recent inbox notes", or an explicit request like "clean up the cellchat notes"), find problems, propose a plan, get explicit confirmation, then execute. Never move, merge, or delete in bulk silently.

Step 1 — Gather signals for the scope

Read the map first for context, then use the structural commands. Scope every list to the folder in question where the command supports it.

• obsidian vault="MyVault" files folder="<scope>" — inventory + spot near-duplicate titles (e.g. "CellChat analysis" vs "CellChat Analysis v2").
• obsidian vault="MyVault" orphans — notes with no incoming links (nothing links to them; candidates for filing/merging/archiving).
• obsidian vault="MyVault" deadends — notes with no outgoing links (often stubs or captures that were never developed).
• obsidian vault="MyVault" search:context query="<topic>" path="<scope>" — compare content of suspected near-duplicates before proposing a merge.
• obsidian vault="MyVault" backlinks path="<file>" — before merging or deleting a note, see what links to it so you don't strand references.

There is no dedicated "duplicates" command; detect duplicates by comparing the titles from files and confirming with search:context / read.

Step 2 — Propose a plan (and wait)

Present a concrete, itemized plan and stop for confirmation. Group by action:

Proposed reorganization for Bioinformatics/cellchat/ (7 notes):

MERGE
- "CellChat analysis.md" + "CellChat analysis (1).md" → keep "CellChat analysis.md",
  fold unique content from the duplicate in, then delete the duplicate.

MOVE
- "Spatial CellChat.md" → Single_Cell/Spatial_Omics/ (topic is spatial, not the tool)

RENAME
- "untitled cellchat.md" → "CellChat LR database notes.md"

No change: 3 notes look fine.

Proceed? I won't move/merge/delete anything until you confirm.

Keep the plan honest about uncertainty — flag guesses so the user can veto them.

Step 3 — Execute only after "yes"

On confirmation, run the moves/renames/deletes through the CLI in the order that keeps links intact (usually: merge content first, then delete the emptied duplicate; move before rename if both apply). Use move, rename, delete, append/read for merges — never raw shell. Report what changed, and append any new folders/categories you created to 00_Index/Folder_Map.md.

Known standing reorg candidates

If the vault's Folder_Map.md calls out known problem areas (legacy folders that overlap a newer one, a subfolder with accumulated near-duplicate titles, etc.), surface them when they're in scope — but still propose-and-confirm before touching anything.

---

Command quick reference

Need	Command
Read the map	obsidian vault="MyVault" read path="00_Index/Folder_Map.md"
Create/file a new note	obsidian vault="MyVault" create path="Folder/Note.md" content="..." silent
Move/relocate a note	obsidian vault="MyVault" move path="Old/Note.md" to="New/Folder"
Rename in place	obsidian vault="MyVault" rename path="Folder/Note.md" name="New Title"
Delete (to trash)	obsidian vault="MyVault" delete path="Folder/Note.md"
List files in a folder	obsidian vault="MyVault" files folder="<scope>"
Orphans / dead-ends	obsidian vault="MyVault" orphans · ... deadends
Search with context	obsidian vault="MyVault" search:context query="..." path="<scope>"
Backlinks to a note	obsidian vault="MyVault" backlinks path="Folder/Note.md"
Append to the map	obsidian vault="MyVault" append path="00_Index/Folder_Map.md" content="- ..."

Run obsidian help <command> to confirm exact params — the CLI is the ground truth.