Vault Organizer

Vault Organizer

Turn a messy markdown vault into a clean, cross-linked, indexed knowledge base that an LLM (or a teammate) can retrieve from fast. Built on Karpathy's principle: treat knowledge like code. Raw sources are source files, the compiled wiki is the build output, the INDEX is the schema, and this skill is the compiler + linter.

The model (3 layers)

| Layer | What | Where | |---|---|---| | RAW | Unprocessed: transcripts, clips, dumps, screenshots | 00_Inbox/raw/, closest topic folder | | COMPILED | Synthesized pages, cross-referenced with [[wikilinks]] | PARA folders (01_–04_) | | SCHEMA | INDEX files, CLAUDE.md, the rules | per-folder INDEX.md + a master index |

Every file carries type: frontmatter (raw | compiled | reference | framework | client | index). See references/standards.md for the frontmatter and INDEX templates.

Workflow

Run these in order. Audit and propose before changing anything. Never delete or move without confirming. Prefer a git repo so changes are reversible.

1. Audit (read-only)

# whole vault:
python3 scripts/audit.py  --stale-days 120 --report /tmp/vault-audit.md
# one subfolder, but resolve [[wikilinks]] against the whole vault (avoids false "broken" flags):
python3 scripts/audit.py  --link-root  --report /tmp/vault-audit.md

Returns a health report: missing frontmatter, broken/missing wikilinks, orphans, missing Related sections, duplicates, stale files, folders without an INDEX. Read it, then show the user the summary table and the top issues. (--json for machine output.)

2. Triage

Group the findings and ask what to fix now vs later. Default priority:

1. Folders without an INDEX (kills retrieval)
2. Missing frontmatter (kills search + Properties)
3. Broken wikilinks (kills the graph)
4. Missing Related sections + orphans (kills discovery)
5. Stale / duplicates (cleanup)

3. Clean (per file)

For each flagged file:

• Add YAML frontmatter (title, type, source, author, created, description, tags) — infer from content, use today's date for created if unknown.
• Add [[wikilinks]] on the first mention of any concept, tool, person, or file that exists elsewhere in the vault.
• Add a ## Related section at the bottom with 3–8 [[wikilinks]] to the most connected pages. Add the file back into the Related of 2–3 of those pages (bidirectional).
• Fix broken wikilinks: repoint to the correct slug, or leave as an intentional stub if the target is worth writing later.

Use the templates in references/standards.md. Do not remove existing frontmatter or links.

4. Organize (propose first)

• Move misfiled items to the right layer/folder (raw → 00_Inbox/raw/, compiled → PARA).
• Normalize filenames to kebab-case; merge or rename duplicates.
• Keep moves small and reversible. List every move and get a yes before running it.

5. Register (the deliverable)

• For each content folder, generate or update INDEX.md: a one-line pointer per file

(- [[file-name]] — short hook), grouped by type, newest or most-important first.

• Build/refresh a master index (e.g. INDEX.md at the root, or a meta/ schema folder)

that links to every folder INDEX.

• This registry is what makes retrieval fast and what you hand to a teammate.

6. Lint (confirm)

Re-run audit.py. Show the before/after counts. The vault is "clean" when frontmatter, INDEX coverage, and broken-link counts are at zero (orphans/stale may remain by choice).

Sending it to a teammate

When the goal is to share the organized vault with a teammate: make sure the master INDEX is current, every folder has its own INDEX, and a short README.md at the root explains the 3-layer model and how to navigate. The README + master INDEX is the entry point.

Rules

• Read-only audit first, always. Surface, don't surprise.
• Never delete or bulk-move without explicit confirmation; recommend committing first.
• Don't touch .obsidian/, .git/, or Claude Code config (settings.json, hooks).
• Match the vault's existing conventions (this one: PARA + the standards in references/standards.md).
• Work in batches; report what changed after each batch.

Files

• scripts/audit.py — read-only scanner, the engine. Run it first and last.
• references/standards.md — frontmatter spec, type taxonomy, INDEX + README templates.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: walidboulanouar
• Source: walidboulanouar/vault-organizer
• License: MIT

Install and usage instructions live in the source repository linked above.