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)

1. 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

1. 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

1. 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:

| Role | Purpose | Detection Signal | |------|---------|-----------------| | Daily Notes | Daily journal entries | Date-named files (YYYY-MM-DD) | | Goals | Goal cascade (3-year → weekly) | Files with goal/review keywords | | Projects | Active projects | Subdirs with CLAUDE.md or project keywords | | Templates | Reusable note structures | Files with template keywords or in Templates/ | | Archives | Completed/inactive content | Folder named Archive(s) or with old dates | | Inbox | Uncategorized captures | Folder named Inbox, or files tagged #inbox |

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:

json
{
  "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.).

4c. Write vault-config.json

Write vault-config.json in the vault root:

json
{
  "name": "User's name",
  "reviewDay": "Sunday",
  "goalAreas": ["Career & Professional", "Health & Wellness"],
  "workStyle": "Direct and concise",
  "setupDate": "2026-02-17",
  "version": "3.1",
  "adoptedVault": true,
  "folderMapping": {
    "dailyNotes": "Daily",
    "goals": "Goals",
    "projects": "Projects",
    "templates": "Templates",
    "archives": "Archive",
    "inbox": "Inbox"
  }
}

4d. Set Environment Variables

Write or update CLAUDE.local.md with env var exports for hooks:

markdown
## Environment Overrides

These env vars allow hooks and scripts to find your folders:

<!--
Export these in your shell profile or they'll be set by session-init:
-->
DAILY_NOTES_DIR={mapped daily notes folder}
GOALS_DIR={mapped goals folder}
PROJECTS_DIR={mapped projects folder}
TEMPLATES_DIR={mapped templates folder}
INBOX_DIR={mapped inbox folder}
ARCHIVES_DIR={mapped archives folder}

Also create .claude/hooks/adopt-env.sh that exports these variables:

bash
#!/bin/bash
# Environment variables for adopted vault folder mapping
# Generated by /adopt — edit vault-config.json and re-run /adopt to update

export DAILY_NOTES_DIR="{mapped daily notes}"
export GOALS_DIR="{mapped goals}"
export PROJECTS_DIR="{mapped projects}"
export TEMPLATES_DIR="{mapped templates}"
export INBOX_DIR="{mapped inbox}"
export ARCHIVES_DIR="{mapped archives}"

Then add a source line to session-init.sh if not already present:

bash
# Source adopted vault env vars if present
ADOPT_ENV="$VAULT_PATH/.claude/hooks/adopt-env.sh"
if [ -f "$ADOPT_ENV" ]; then
    source "$ADOPT_ENV"
fi

Phase 5: Scaffold Missing Pieces

Check what's missing and offer to create it. Always ask before creating.

5a. Goal Cascade Files

If the goals folder is empty or newly created:

• "Your goals folder is empty. Want me to create the goal cascade? (3-year vision, yearly goals, monthly goals, weekly review)"
• If yes: copy the standard templates, adapting paths to the user's folder names
• If no: skip

5b. Templates

If the templates folder is empty or newly created:

• "Want me to add standard templates? (Daily, Weekly Review, Project)"
• If yes: copy templates, adapting internal links to the user's folder names
• If no: skip

5c. CLAUDE.local.md.template

If CLAUDE.local.md.template doesn't exist:

• Copy it from the standard template
• Adapt any folder references

5d. Claude Config Directories

Ensure these directories exist (create silently):

• .claude/skills/ (for future skill additions)
• .claude/rules/
• .claude/hooks/
• .claude/agents/

Copy standard rules files if .claude/rules/ is empty:

• markdown-standards.md
• productivity-workflow.md
• project-management.md
• task-tracking.md

Phase 6: Verify & Next Steps

6a. Validation

Run quick checks:

• vault-config.json is valid JSON (read it back)
• All mapped folders exist
• CLAUDE.md is present and non-empty
• .claude/hooks/adopt-env.sh is present and executable

6b. Summary

Present a summary:

Adoption complete!

Vault: /path/to/vault
Method: PARA-like (preserved your existing structure)
Mapped folders:
  Daily Notes → Daily/
  Goals       → Goals/
  Projects    → Projects/
  Templates   → Templates/
  Archives    → Archive/
  Inbox       → Inbox/

Created:
  ✓ CLAUDE.md (vault context)
  ✓ vault-config.json (preferences)
  ✓ .claude/hooks/adopt-env.sh (folder mapping)
  ✓ Goal cascade files (4 files)
  ✓ Standard templates (3 files)

Your vault structure is unchanged — only configuration files were added.

6c. Next Steps

Suggest what to do next:

• "Try /daily to create today's note using your vault's structure"
• "Try /review for a guided weekly review"
• "Run /push to commit these changes to git"
• "Edit CLAUDE.local.md for private preferences (not committed to git)"

Error Handling

• Not in a vault: If no .obsidian directory found, warn: "This doesn't look like an Obsidian vault. Continue anyway?"
• Already adopted: If vault-config.json exists with adoptedVault: true, ask: "This vault was already adopted. Re-run adoption? (This will regenerate config files.)"
• Permission errors: If .claude/ can't be written, suggest checking permissions
• Empty vault: If no .md files found, suggest using /onboard with the template instead

Integration

Works with:

• /onboard — adopt replaces onboard for existing vaults
• /daily — uses mapped daily notes folder
• /weekly — uses mapped goals folder
• /review — respects adopted vault structure
• /push — commits adoption changes
• All hooks — read env vars from adopt-env.sh