Vault Organizer — AI skill for Claude Code

Vault Organizer

Clean up, organize, and build a retrieval registry for any markdown knowledge base (Obsidian, Logseq, a PARA second brain, or a plain folder of `.md` files) using **Andrej Karpathy's 3-layer LLM-wiki method**: RAW sources, a COMPILED wiki, and a SCHEMA/index layer.

Treat your knowledge like code. Raw notes are source files, the cross-linked wiki is the build output, the `INDEX` is the schema, and this tool is the compiler and the linter.

It ships as a **skill** for AI coding agents (Claude Code, etc.) and also runs **standalone** as a zero-dependency Python script.

Why

Most "second brains" rot: files with no frontmatter, dead `[[wikilinks]]`, orphan pages nothing links to, folders with no index. That kills retrieval, both for you and for an LLM. This tool finds all of it, fixes it, and builds the indexes that make any file fast to recall.

Quick start (standalone)

No install. Pure Python standard library.

# audit a whole vault (read-only, never edits anything)
python3 scripts/audit.py /path/to/your/vault --report audit.md

# audit one subfolder but resolve [[wikilinks]] against the whole vault
python3 scripts/audit.py /path/to/vault/subfolder --link-root /path/to/your/vault

# machine-readable output
python3 scripts/audit.py /path/to/your/vault --json

You get a health report: missing frontmatter, broken/missing wikilinks, orphan pages, missing `## Related` sections, duplicate filenames, stale files, and folders without an `INDEX`.

Use it as an agent skill

Drop this folder into your agent's skills directory:

# Claude Code (project or global)
cp -r vault-organizer ~/.claude/skills/vault-organizer
# or .claude/skills/ in your project, or .agents/skills/

Then just ask: *"organize my vault"*, *"clean up my notes"*, *"build an index for this folder"*, *"lint my knowledge base"*. The agent runs the audit, shows you the issues, and works the 6-step workflow with you.

The workflow

1. Audit (read-only) —