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

adopt