Analyze an existing Obsidian vault, classify its organization pattern, assess health, and overlay the Minions layer (indexes, frontmatter, entity classification). Preserves existing structure by default. USE when: migrate, import vault, convert vault, analyze vault, vault migration, add minions to vault, upgrade vault, /minions-migrate.
Overlay the Minions layer onto an existing Obsidian vault. Read-only analysis first, modifications only after explicit approval.
SKILL_DIR = <directory containing this SKILL.md>
SHARED_DIR = {SKILL_DIR}/../_shared
CONVENTIONS = {SHARED_DIR}/vault-conventions.md
PATTERNS = {SHARED_DIR}/vault-patterns.md
PLAYBOOK = {SKILL_DIR}/references/migration-playbook.md
Resolve all paths at the start. If _shared/vault-conventions.md is missing, abort with: "Cannot find vault-conventions.md at {SHARED_DIR}. Is the skill installed correctly?"
If user provided a path argument:
VAULT_DIR = <user-provided path> (expand ~)
Else:
Ask: "Which vault should I migrate? Provide the full path."
VAULT_DIR = user's answer
Validate:
- VAULT_DIR exists and is a directory
- Contains at least 5 .md files (sanity check)
- If _Meta/state.json exists → "This vault already has a Minions layer. Run /minions-init repair instead."
CRITICAL: No file modifications in this phase. Read and analyze only.
See references/agent-prompts.md for the 3 Discovery Agent prompts.
Print: Phase 1: Discovery [running...]
| Agent | Scope | Returns |
|---|---|---|
| Agent A | File inventory + folder structure (max 4 levels deep) | File counts by extension, .md counts by folder, folder tree |
| Agent B | Frontmatter audit (ALL .md files) + tag inventory | Frontmatter field frequencies, type values, tag frequencies |
| Agent C | Link analysis + orphan detection | Outlink/inlink counts, averages, top-linked files, orphan list |
Wait for all 3 to complete. Merge results.
Read {PATTERNS} and {PLAYBOOK} for recognition guides. Classify the vault based on:
deals/, outreach/, finance/, tasks/, strategy/; AGENTS.md at root; frontmatter types like lead, client, meetingIf no single pattern dominates, classify as "Hybrid" with the top 2 detected patterns.
Print: Phase 1: Discovery [done]
PAUSE after this phase. Present findings, then ask the user before proceeding.
Print the full report:
══════════════════════════════════════════════════
Vault Health Report — {VAULT_DIR}
══════════════════════════════════════════════════
Pattern: {detected pattern} ({confidence}%)
Total files: {count} ({md_count} markdown, {other_count} other)
Folder Stats:
{folder}: {count} files
...
Frontmatter:
With frontmatter: {pct}%
With 'type' field: {pct}%
With 'tags' field: {pct}%
Consistency score: {score}/10
Links:
Avg outlinks/file: {avg}
Avg inlinks/file: {avg}
Link density: {low|medium|high}
Tags:
Unique tags: {count}
Top 10: {tag (count), ...}
Orphans: {count} files ({pct}%)
Anti-patterns detected:
{list from vault-patterns.md anti-patterns}
Overall Health: {A|B|C|D}
══════════════════════════════════════════════════
Health grading:
PAUSE. Ask the user:
How should I proceed?
1. Overlay mode (default) — Add Minions layer on top. No files moved.
2. Restructure mode — Move entity files into Minions folders (People/, Projects/, etc.)
3. Skip phases — Tell me which to skip (e.g., "skip frontmatter")
Choose [1/2/3] or type specific instructions:
Store the user's choice as MIGRATION_MODE (overlay | restructure). Store any skip preferences.
PAUSE. Establish the user's vault organization rules. Read references/preferences-interview.md for the full question set, smart defaults, and output format.
{VAULT_DIR}/_Meta/preferences.json — the single source of truth for all Minion skills.vault-conventions.md → "CLAUDE.md Vault Section"Print: Phase 2.5: Preferences saved → _Meta/preferences.json + CLAUDE.md updated.
Print: Phase 3: Classification [running...]
First detect the vault archetype — this determines which classification system to use.
If vault has folders like People/, Projects/, Technologies/, Concepts/:
ARCHETYPE = entity-vault
→ Classify into entity types (person, project, technology, etc.)
If vault has folders like deals/, outreach/, finance/, strategy/, tasks/:
ARCHETYPE = business-vault
→ Classify into business functions (sales, research, strategy, etc.)
If vault has both patterns or neither clearly:
ARCHETYPE = hybrid
→ Use BOTH classification systems in parallel
Heuristics (priority order):
People/ or Contacts/ → person. Sources/, papers/, literature/ → source. See {PATTERNS}.type field — use as-is if it maps to a Minions entity type. Map research → source.authors, doi, isbn, or url + year fields → source.#person, #project, #company, #paper, #book, #article, etc.Types: person | project | technology | organization | concept | place | event | source | journal | note
For business operations vaults where files are organized by function, not entity type:
| Folder Signals | Business Function | Domain |
|---|---|---|
deals/, clients/, customers/ | sales | sales |
outreach/, leads/, pipeline/ | sales-pipeline | sales |
research/, science/, analysis/ | research | research |
strategy/, planning/, okrs/ | strategy | strategy |
finance/, invoices/, mrr/ | finance | finance |
tasks/, backlog/, kanban/ | operations | ops |
notes/meetings/ | meetings | ops |
notes/decisions/ | decisions | strategy |
experiments/ | experiments | product |
weekly/, journal/, daily/ | journal | general |
docs/, architecture/ | documentation | engineering |
market/, competitors/ | market-intelligence | research |
archive/ | archive | archive |
Each file gets: function, domain, and optionally an entity_type if it represents a specific entity (e.g., a competitor profile in market/competitors/docebo/ → function=market-intelligence, entity_type=organization).
See references/agent-prompts.md → "Classification Agent" for the full sub-agent prompt.
If vault has < 100 .md files:
Classify inline (no sub-agents).
If vault has >= 100 .md files:
1. Build FILE_BATCH arrays from discovery data (frontmatter info from Agent B)
2. Split into batches of ~100 files
3. Spawn one Classification Agent per batch (ALL in single message)
4. Agents return JSON classifications — they never write files
5. Merge results into classification map
Classification map structure per file:
{
file_path: {
name: "from frontmatter or filename",
type: "entity type (if applicable)",
function: "business function (if applicable)",
domain: "inferred from folder/tags",
is_entity: true/false
}
}
Phase 3: Classification [done]
Vault archetype: {entity-vault | business-vault | hybrid}
By entity type (if applicable):
person: {N}, project: {N}, organization: {N}, ...
By business function (if applicable):
sales: {N}, research: {N}, strategy: {N}, ...
Unclassified: {N}
PAUSE. Ask: "Classification looks right? Any corrections? (e.g., 'market/ files are research, not sales')"
Apply corrections.
Skip if user requested skip. Print: Phase 4: Frontmatter Normalization [running...]
For each entity file (type != "note"):
name: from classification maptype: from classification mapdomain: from classification mapmemory_type: episodic (journal), semantic (established notes), procedural (rules/preferences)status: based on file mtime — new (<7d), active (<30d), stale (30-90d), inactive (>90d)created: from existing created/date field, or file ctime (YYYY-MM-DD)updated: from file mtime (YYYY-MM-DD)aliases: generate with wikilink prefix (@Name for people, +Name for orgs, #Name for projects)CRITICAL: Never overwrite existing frontmatter values. Only add fields that are missing. If type already exists and differs from classification, keep the existing value.
Track: files modified count, fields added count.
Print: Phase 4: Frontmatter Normalization [done] — {N} files updated, {M} fields added
Print: Phase 5: Index Generation [running...]
Create directories:
mkdir -p {VAULT_DIR}/_Index
mkdir -p {VAULT_DIR}/_Meta
Write to {VAULT_DIR}/_Index/catalog.yaml:
# Minions Entity Catalog — migrated {YYYY-MM-DD}
# Auto-managed by /minions-remember and /minions-organize