/adopt

name: adopt
description: Scaffold the PKM system onto an existing Obsidian vault. Scans your vault structure, maps folders interactively, and generates configuration — no template required.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion
model: sonnet
user-invocable: true

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:

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