Obsidian Vault Kit

obsidian-vault-kit

A Claude Code plugin that bundles the Obsidian indexing & integration workflow for the Neo4j GraphAcademy compilation vault so it travels as one drop-in unit. The vault compiles four GraphAcademy "Fundamentals" courses (neo4j-fundamentals, cypher-fundamentals, modeling-fundamentals, importing-fundamentals) into one nine-topic graduate-style course.

What's inside

Component	Path	Role
Skill	skills/obsidianize-module/	Per-topic integration pipeline (schema → tags → wikilinks → verify → commit).
Skill	skills/concept-hub/	Create / normalize a concept hub and wire its bidirectional links.
Script	scripts/check-vault.py	Deterministic invariant checker (Python stdlib only; no third-party deps, no model). Detects dangling wikilinks, missing frontmatter, appears_in backlink gaps, and hub-gap candidates. Reports only — never edits.
Wrapper	scripts/check-vault.sh	Thin exec python3 check-vault.py wrapper, so the hook and skills have a stable entry point regardless of implementation language.
Hook	hooks/hooks.json	Runs the checker on Stop (end of turn) so out-of-band edits surface even when no skill was invoked.
Agent	agents/vault-librarian.md	Invoked (never auto-fired) remediation persona that reads the checker's findings and fixes them per SCHEMA.md.

The canonical spec the whole kit enforces lives in the vault, not here: notes/_meta/SCHEMA.md.

Design notes

• Detection is deterministic; remediation is judgment. The hook + script guarantee problems are detected on every turn end. Fixing is left to a human or an explicitly-invoked agent/skill — the hook never auto-edits, which avoids an edit→hook→fix→edit loop and keeps handover-quality content under review.
• Surface where it runs. Skills, hooks, and the agent are consumed by Claude Code (CLI and the Desktop "Code" tab). They do not run inside Claude Cowork — but the checker is a plain script, so after any Cowork/MCP session you (or a Claude Code session) can run it to detect whatever drifted.
• Portable by construction. The checker is Python 3 stdlib only (uses os.walk, no third-party packages, no find binary — which on macOS can be TCC-blocked — and no bash-version dependency). Nothing to install.

Run the checker manually

python3 obsidian-vault-kit/scripts/check-vault.py <path-to-repo-or-vault>
python3 obsidian-vault-kit/scripts/check-vault.py notes --strict   # exit 1 on any ERROR

Exit codes: 0 clean / report-only · 1 --strict with ERROR-class findings · 2 scan failed (root unreadable — distinct from "no vault here").

Install (when distributing)

This repo doubles as a single-plugin marketplace (.claude-plugin/marketplace.json). A collaborator who clones it can add the marketplace and install obsidian-vault-kit, or run Claude Code with --plugin-dir ./obsidian-vault-kit for local development.