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

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

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

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

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:

{ "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:

{ "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:

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:

#!/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:

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