Obsidian Vault Adoption

Adopt Skill

Bring Your Own Vault (BYOV) — install the Claude PKM system onto an existing Obsidian vault.

Usage

/adopt    # Run from the root of your existing Obsidian vault

When to Use

• You have an existing Obsidian vault and want to add the Claude PKM system
• You don't want to start from the vault template
• You want to keep your current folder structure

Phase 1: Scan Vault Structure

Analyze the existing vault to understand its organization.

Steps

1. List top-level directories using ls, excluding system dirs (.obsidian, .git, .claude, .trash, .claude-plugin)

2. For each directory, gather signals:

   • Count .md files (using Glob)
   • Check for date-named files (YYYY-MM-DD*.md) — indicates daily notes
   • Grep for goal/review/template keywords in filenames and content
   • Check for existing CLAUDE.md in subdirs — indicates projects

3. Detect organization method based on signals:

   • PARA: Folders named Projects, Areas, Resources, Archives
   • Zettelkasten: Numeric-prefixed notes, heavy wiki-linking, flat structure
   • Johnny Decimal: 00-09, 10-19 style folder names
   • LYT (Linking Your Thinking): Folders named Atlas, Calendar, Cards, Extras, Sources
   • Flat: Few folders, most files at root
   • Custom: None of the above patterns match

4. Present findings to the user:

   Vault scan complete!
   
   Found 342 notes across 8 folders:
     Daily/           → 180 notes (date-named — likely daily notes)
     Projects/        → 45 notes (has CLAUDE.md files — likely projects)
     Goals/           → 12 notes (contains goal keywords)
     Templates/       → 8 notes (contains template keywords)
     Archive/         → 67 notes
     Inbox/           → 15 notes
     Resources/       → 10 notes
     Meeting Notes/   → 5 notes
   
   Detected method: PARA-like structure

Phase 2: Map Folders to Roles

Use AskUserQuestion to confirm or correct the detected mappings.

Roles to Map

Each role maps a PKM function to a folder in the user's vault:

Interactive Mapping

For each role, ask the user to confirm or correct:

Question format (use AskUserQuestion):

• "Which folder holds your daily notes?"
• Options: detected candidate(s), "I don't have one (create it)", "Skip — I don't use this"
• For optional roles (Inbox), include "Skip" as a default

Edge cases:

• Existing CLAUDE.md at root: Ask the user — back up as CLAUDE.md.backup or merge content
• No candidate for a role: Offer to create the folder
• Multiple candidates: Present all and let the user choose

Save Mappings

Store the folder mapping for use in later phases:

dailyNotes → "Daily"
goals → "Goals"
projects → "Projects"
templates → "Templates"
archives → "Archive"
inbox → "Inbox"     (or null if skipped)

Phase 3: Personalize Preferences

Ask the same 4 questions as /onboard:

Question 1: Your name

• "What should I call you?"
• Used for personalized prompts and greetings

Question 2: Preferred review day

• "What day do you prefer for your weekly review?"
• Options: Sunday (Recommended), Saturday, Monday, Friday
• Used by /review auto-detection and session-init nudges

Question 3: Primary goal areas

• "Which areas are most important to you right now? (Pick 2-4)"
• Options: Career & Professional, Health & Wellness, Relationships, Personal Growth
• Also offer: Financial, Creativity & Fun, Learning, Other
• multiSelect: true
• Used to customize goal template suggestions

Question 4: Work style

• "How do you prefer Claude to interact?"
• Options: Direct and concise (Recommended), Coaching and challenging, Detailed and thorough, Minimal — just do the task
• Sets output style preference

Phase 4: Generate Configuration

4a. Write settings.json

Write .claude/settings.json with permissions scoped to the user's actual folders:

{
  "permissions": {
    "allow": [
      "Read",
      "Write **/{mapped-daily}/**",
      "Write **/{mapped-goals}/**",
      "Write **/{mapped-projects}/**",
      "Write **/{mapped-templates}/**",
      "Edit **/{mapped-daily}/**",
      "Edit **/{mapped-goals}/**",
      "Edit **/{mapped-projects}/**",
      "Glob",
      "Grep"
    ]
  }
}

Replace {mapped-*} with actual folder names from Phase 2.

4b. Write root CLAUDE.md

Generate a root CLAUDE.md that describes the user's actual vault structure. Use the same format as the template's CLAUDE.md but with:

• Their folder names in the Directory Structure table
• Their goal areas in the System Purpose section
• Their actual skills table (same as template)
• Cascade section adapted to their folder names

If the user had an existing CLAUDE.md, merge their content into the appropriate sections (preserve their mission statement, custom conventions, etc.).