julianobarbosa/vault-setup

vault-setup-skill

Interactive vault configurator — asks one free-text question, infers your role and folders, builds a personalized Obsidian vault with CLAUDE.md and companion skill links.

Directory Structure

vault-setup-skill/
├── SKILL.md                          # This file (routing + quick ref)
├── RoleTemplates.md                  # Keyword-to-folder mapping table
├── PluginRecommendations.md          # Obsidian plugins by role type
├── Workflows/
│   ├── Setup.md                      # Main 6-step setup flow
│   ├── ImportFiles.md                # File import guidance
│   └── Verify.md                     # Post-setup verification
├── Tools/
│   ├── VaultBuilder.py               # CLI: create, verify, inject-global
│   └── VaultBuilder.help.md          # Tool documentation
└── scripts/
    └── process_docs_to_obsidian.py   # Bulk file import to inbox/

Workflow Routing

| Intent | Workflow | Tool | |--------|----------|------| | Set up a new vault | Workflows/Setup.md | Tools/VaultBuilder.py create | | Import existing files | Workflows/ImportFiles.md | scripts/process_docs_to_obsidian.py | | Verify vault setup | Workflows/Verify.md | Tools/VaultBuilder.py verify | | Add vault to global context | Workflows/Setup.md Step 5 | Tools/VaultBuilder.py inject-global | | Choose Obsidian plugins | PluginRecommendations.md | — | | Understand folder mapping | RoleTemplates.md | — |

Examples

"Set up my Obsidian vault"              → Workflows/Setup.md
"I want to create a second brain"       → Workflows/Setup.md
"Import my documents into the vault"    → Workflows/ImportFiles.md
"Verify my vault is set up correctly"   → Workflows/Verify.md
"What plugins should I install?"        → PluginRecommendations.md
"Add this vault to my global config"    → Workflows/Setup.md Step 5

Quick Reference

Base folders (always created): inbox/, daily/, projects/, archive/

Additional folders detected from keywords — see RoleTemplates.md for full mapping.

Companion skills (linked, not created): daily-skill, tldr-skill, obsidian-master-skill

Troubleshooting

| Problem | Cause | Fix | |---------|-------|-----| | click not found when running VaultBuilder.py | Missing dependency | pip install click | | Vault folders created but Obsidian doesn't see them | Obsidian not pointed at vault root | Open Obsidian → "Open folder as vault" → select the vault directory | | inject-global says "Already configured" but Claude doesn't see context | Vault path in CLAUDE.md doesn't match exactly | Check ~/.claude/CLAUDE.md for the vault path — it must be the resolved absolute path | | Symlink shows [BROKEN] in verify | Target skill directory was moved or deleted | Re-create the symlink: ln -sf /path/to/skill ~/.claude/skills/skill-name | | process_docs_to_obsidian.py shows encoding warnings | Source files contain non-UTF-8 characters | Review warned files manually; convert source encoding with iconv if needed |

Edge Cases

• Empty keywords: If --role-keywords is empty, only base folders are created (inbox, daily, projects, archive)
• Vault path doesn't exist: VaultBuilder creates it automatically via mkdir -p
• Running create twice: Safe — folders use exist_ok=True, CLAUDE.md is overwritten (back up first if customized)

Gotchas

• inject-global mutates ~/.claude/CLAUDE.md with absolute path: If you later move the vault, the global config still points to the old path and Claude silently loads nothing. Re-run inject-global after any vault relocation.
• Re-running create overwrites a customized CLAUDE.md: Folder creation uses exist_ok=True (safe) but CLAUDE.md is unconditionally rewritten. Back up first if you've hand-edited vault-level instructions.
• process_docs_to_obsidian.py silently skips non-UTF-8 files: Latin-1 or Windows-1252 source files emit a warning and are not imported. The summary report doesn't flag them as failures — grep stderr for "encoding" before trusting the count.
• Symlinks to companion skills break on PAI directory restructure: Verify shows [BROKEN] only if the symlink target is missing entirely; a renamed-but-existing target appears valid yet routes to the wrong skill. Re-run verify after any PAI skill reorganization.
• Empty --role-keywords is not an error: The vault gets only base folders (inbox/daily/projects/archive) with no warning. If you expected role-specific folders, check the inferred keywords in the setup transcript.
• Obsidian doesn't see the vault until "Open folder as vault": Creating the directory tree is not enough — Obsidian must be pointed at the vault root explicitly. New users often think the script failed because Obsidian shows an empty workspace.