# Vault Organizer

> Clean up, organize, and build a retrieval registry for a markdown knowledge base (Obsidian / PARA second brain) using Karpathy's 3-layer LLM-wiki method: RAW sources, COMPILED wiki, SCHEMA/index. Runs a read-only audit (missing frontmatter, broken or missing [[wikilinks]], orphan pages, missing Related sections, stale files, duplicate names, folders without an INDEX), then fixes them, enforces consistent structure, and generates per-folder + a master INDEX so any file is fast to find. Use when the user says: "clean up my folders / vault", "organize my files", "build an index or registry", "make my notes retrievable", "lint my knowledge base", "tidy my second brain", "standardize frontmatter and wikilinks", or wants a folder reorganized for better recall.

- Skill: `walidboulanouar/vault-organizer` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add walidboulanouar/vault-organizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/walidboulanouar/vault-organizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: walidboulanouar (https://skillmd.com/u/walidboulanouar)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/walidboulanouar/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)
```bash
# whole vault:
python3 scripts/audit.py <vault_root> --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 <subfolder> --link-root <vault_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.