astoreyai/skills/vault-keeper

vault-keeper

Maintains Obsidian vault organization and structure according to established conventions.

Description

The vault-keeper skill ensures the Obsidian vault at ~/Documents/Obsidian/Aaron/ maintains its organizational structure and follows established naming conventions. It enforces the numbered folder hierarchy (00_Navigation/, 01_Academic/, etc.) and keeps the root level clean.

Capabilities

Structure Enforcement

• Monitors root-level files and ensures only allowed files remain at root
• Validates numbered folder hierarchy (00-08)
• Prevents clutter by auto-organizing misplaced files
• Maintains consistent folder structure across sessions

File Organization Rules

Root Level (4 files only):

• Home.md - Main vault dashboard
• CLAUDE.md - Vault guidance for Claude Code
• README.md - Vault metadata and information
• (NO other .md files at root)

Numbered Folder Hierarchy:

• 00_Navigation/ - Dashboards and Maps of Content
  • Dashboards/ - All dashboard files (*-Dashboard.md)
  • Maps-of-Content/ - All MOC files (*MOC.md)
• 01_Academic/ - Research notes, coursework, dissertation
• 02_Professional/ - Business ventures (KYMERA Holdings)
• 03_Technical/ - Commands, prompts, configurations
• 04_Finance/ - Stock market, trading strategies
• 05_Mobile/ - Mobile quick references
• 06_Archive/ - Historical content and backups
• 07_System/ - System files, indexes, references
  • Indexes/ - Tags Index, Unlinked Mentions, Daily Notes
• 08_Enso/ - Sync scripts and Enso-related content

Non-Numbered Folders (allowed):

• Daily/ - Daily notes with sessions/meetings
• Projects/ - Active project notes (xai, stoch, cc-flow, trading)
• Knowledge/ - Reference library (Academic, Prompts)
• Templates/ - Obsidian note templates

Task Management

Canonical Source: 00_Navigation/Dashboards/Todo-Dashboard.md

• All task tracking happens in Todo-Dashboard.md
• No duplicate task files (todo.md, Todo List.md) permitted
• SessionEnd hook auto-saves tasks

Validation Actions

When invoked, vault-keeper:

1. Scans root directory for .md files
2. Identifies files that don't belong at root
3. Suggests proper locations based on file type/name
4. Optionally moves files to correct locations
5. Reports on vault health and structure compliance

Usage

# Invoke skill to check vault structure
/vault-keeper check

# Auto-organize misplaced files
/vault-keeper organize

# Report vault statistics
/vault-keeper stats

# Validate numbered folder structure
/vault-keeper validate-structure

File Type Detection

The skill uses these heuristics to organize files:

Dashboards (*-Dashboard.md) → 00_Navigation/Dashboards/ MOCs (* MOC.md) → 00_Navigation/Maps-of-Content/ Indexes (*Index.md, *Mentions.md) → 07_System/Indexes/ Daily Notes (YYYY-MM-DD.md) → Daily/ Academic Content (course names, research keywords) → 01_Academic/ Technical Reports (technical keywords) → 03_Technical/ Personal References (Places.md, Restaurants.md) → 05_Mobile/ or delete

Integration

SessionEnd Hook

Auto-validates vault structure on session exit:

#!/usr/bin/env python3
import os
from pathlib import Path

VAULT = Path.home() / "Documents/Obsidian/Aaron"
ALLOWED_ROOT = {"Home.md", "CLAUDE.md", "README.md"}

def validate():
    root_files = set(f.name for f in VAULT.glob("*.md"))
    violations = root_files - ALLOWED_ROOT
    if violations:
        print(f"⚠️  Vault structure violation: {len(violations)} files at root")
        print(f"Files: {', '.join(violations)}")
        return False
    print("✅ Vault structure: OK")
    return True

if __name__ == "__main__":
    validate()

Configuration

vault-keeper.yaml

vault_path: ~/Documents/Obsidian/Aaron
allowed_root_files:
  - Home.md
  - CLAUDE.md
  - README.md
numbered_folders:
  - 00_Navigation
  - 01_Academic
  - 02_Professional
  - 03_Technical
  - 04_Finance
  - 05_Mobile
  - 06_Archive
  - 07_System
  - 08_Enso
auto_organize: false  # Set to true for automatic file moves

Examples

Example 1: Detecting Root Clutter

User creates new file: ~/Documents/Obsidian/Aaron/random-note.md

vault-keeper check:
⚠️  Found 1 file at root that doesn't belong:
  - random-note.md (no clear category)

Suggestions:
  - Move to Projects/ if project-related
  - Move to 05_Mobile/ if quick reference
  - Move to appropriate numbered folder based on content

Example 2: Auto-Organizing Dashboard

User creates: ~/Documents/Obsidian/Aaron/Finance-Dashboard.md

vault-keeper organize:
✅ Moved Finance-Dashboard.md → 00_Navigation/Dashboards/
Reason: Matches *-Dashboard.md pattern

Example 3: Vault Health Report

vault-keeper stats:

📊 Vault Health Report
Root files: 3/3 (compliant)
Numbered folders: 9/9 (complete)
Total files: 185 markdown files
Recent changes: 12 files modified in last 24h

Structure: ✅ HEALTHY
Task management: ✅ Consolidated (Todo-Dashboard.md only)
Archives: ✅ Clean (06_Archive/ contains dated backup)

Maintenance Commands

# Check vault structure
python ~/.claude/skills/vault-keeper/validate_structure.py

# Auto-organize misplaced files
python ~/.claude/skills/vault-keeper/auto_organize.py

# Generate vault report
python ~/.claude/skills/vault-keeper/vault_report.py

Notes

• Respects user's numbered folder system philosophy
• Prevents root-level clutter by design
• Integrates with existing SessionEnd hooks
• Non-destructive by default (suggests moves, doesn't execute without confirmation)
• Maintains compatibility with Obsidian's graph view and backlinks

See Also

• obsidian-memory-keeper - Daily notes and session tracking
• todo-keeper - Task persistence and management
• memory-keeper - CLAUDE.md updates