How do I install the Obsidian Migrate skill?

Run npx skillmds@latest add melgarafael/obsidian-migrate in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Obsidian Migrate safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Obsidian Migrate?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Obsidian Migrate free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Obsidian Migrate?

melgarafael (@melgarafael) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Obsidian Migrate by melgarafael — Agent Skill

Name: Obsidian Migrate
Author: melgarafael

Obsidian Migrate

Esta skill deve ser usada quando o usuario tem um vault Obsidian ja existente e quer adotar o padrao obsidian-master-kit SEM destruir a estrutura atual. Detecta o estado do vault, faz backup automatico, roda shadow-scan com embeddings, descobre areas reais via clustering (HDBSCAN), propoe mapping pasta->area adaptativo, executa migracao em lotes com approval humano obrigatorio, e oferece rollback. Adocao hibrida (Opcao C). Invocada via /obsidian-master-kit:migrate ou quando o usuario pede "quero usar o kit no meu vault que ja existe". Nunca executa automaticamente sem aprovacao explicita.

melgarafael d81756d 3 files · 55.0 KB Updated Sep 17, 2026

File contents

obsidian-migrate

Adota o obsidian-master-kit em um vault Obsidian existente sem quebrar o que ja funciona. Segue a Opcao C (hibrida): descoberta de areas reais via clustering + approval humano por lote + rollback disponivel + backup obrigatorio antes de qualquer movimento.

Quando usar

Usuario diz: "quero usar o kit no vault que ja tenho", "adota o obsidian-master-kit no meu Obsidian atual", "migra meu vault pro kit sem apagar nada"
Usuario invoca /obsidian-master-kit:migrate
Usuario aponta pra uma pasta que ja tem .md e quer estrutura do kit

Quando nao usar

Vault vazio — use obsidian-init (scaffold do zero)
Vault ja migrado (tem .obsidian-master/marker.json) — use obsidian-librarian
Usuario quer reorganizacao continua de vault ja migrado — use obsidian-organizer (Epic 04, futuro)

Como usar — fluxo canonico

A skill tem 6 etapas, cada uma com aprovacao do usuario. Nunca pula etapa nem executa sem confirmacao.

Etapa 1 — Deteccao de estado

python3 ${CLAUDE_PLUGIN_ROOT}/skills/obsidian-migrate/scripts/migrate.py status --vault PATH

Retorna um de:

empty — pasta nao tem .md. Sugere /obsidian-master-kit:init.
existing — tem .md, sem marker. Pronto pra migrar.
already_migrated — tem .obsidian-master/marker.json. Usa obsidian-librarian.

Etapa 2 — Shadow scan + backup (Wave 2)

migrate.py shadow-scan --vault PATH

Cria backup (vault.backup-YYYYMMDD-HHMMSS/), inicializa DB, roda scanner sem mover arquivos. Output: contagem por pasta + total + tamanho do DB.

Etapa 3 — Clustering (Wave 3)

migrate.py cluster --vault PATH [--ai-label]

HDBSCAN sobre embeddings + TF-IDF pra label candidato. Opcional: --ai-label pede label via Claude.

Etapa 4 — Proposta de mapping (Wave 4)

migrate.py propose --vault PATH

Gera .obsidian-master/migration-proposal.md: tabela pasta -> cluster dominante -> area proposta. Usuario revisa/edita.

Etapa 5 — Plan + approval (Wave 5)

migrate.py plan --vault PATH
migrate.py approve --batch 1 [--batch all]

Gera registros em migration_plan em lotes de 20. Approval interativo por nota (y/n/a/s).

Etapa 6 — Execute + rollback (Wave 6)

migrate.py apply --batch 1 [--batch all]
migrate.py rollback --batch N   # se precisar reverter

Aplica os renames dos approved, refatora wikilinks que quebrariam, emite eventos, e ao terminar cria .obsidian-master/marker.json com migration_completed=true.

Garantias

Backup obrigatorio: nunca move nada sem ter um .backup-* intacto
Approval por lote: usuario aprova 20 notas por vez, nunca o vault inteiro de um golpe
Rollback disponivel: cada batch aplicado pode ser revertido
Opcao C: descoberta de areas respeita o que ja existe; o kit adapta ao vault, nao o vault ao kit

---name: obsidian-migratedescription: Esta skill deve ser usada quando o usuario tem um vault Obsidian ja existente e quer adotar o padrao obsidian-master-kit SEM destruir a estrutura atual. Detecta o estado do vault, faz backup automatico, roda shadow-scan com embeddings, descobre areas reais via clustering (HDBSCAN), propoe mapping pasta->area adaptativo, executa migracao em lotes com approval humano obrigatorio, e oferece rollback. Adocao hibrida (Opcao C). Invocada via /obsidian-master-kit:migrate ou quando o usuario pede "quero usar o kit no meu vault que ja existe". Nunca executa automaticamente sem aprovacao explicita.---# obsidian-migrateAdota o `obsidian-master-kit` em um vault Obsidian existente sem quebrar o que ja funciona.Segue a **Opcao C (hibrida)**: descoberta de areas reais via clustering + approval humanopor lote + rollback disponivel + backup obrigatorio antes de qualquer movimento.## Quando usar- Usuario diz: "quero usar o kit no vault que ja tenho", "adota o obsidian-master-kit no meu Obsidian atual", "migra meu vault pro kit sem apagar nada"- Usuario invoca `/obsidian-master-kit:migrate`- Usuario aponta pra uma pasta que ja tem .md e quer estrutura do kit## Quando **nao** usar- Vault vazio — use `obsidian-init` (scaffold do zero)- Vault ja migrado (tem `.obsidian-master/marker.json`) — use `obsidian-librarian`- Usuario quer reorganizacao continua de vault ja migrado — use `obsidian-organizer` (Epic 04, futuro)## Como usar — fluxo canonicoA skill tem 6 etapas, cada uma com aprovacao do usuario. Nunca pula etapa nem executasem confirmacao.### Etapa 1 — Deteccao de estado```bashpython3 ${CLAUDE_PLUGIN_ROOT}/skills/obsidian-migrate/scripts/migrate.py status --vault PATH```Retorna um de:- `empty` — pasta nao tem .md. Sugere `/obsidian-master-kit:init`.- `existing` — tem .md, sem marker. Pronto pra migrar.- `already_migrated` — tem `.obsidian-master/marker.json`. Usa `obsidian-librarian`.### Etapa 2 — Shadow scan + backup (Wave 2)```bashmigrate.py shadow-scan --vault PATH```Cria backup (`vault.backup-YYYYMMDD-HHMMSS/`), inicializa DB, roda scanner sem moverarquivos. Output: contagem por pasta + total + tamanho do DB.### Etapa 3 — Clustering (Wave 3)```bashmigrate.py cluster --vault PATH [--ai-label]```HDBSCAN sobre embeddings + TF-IDF pra label candidato. Opcional: `--ai-label` pedelabel via Claude.### Etapa 4 — Proposta de mapping (Wave 4)```bashmigrate.py propose --vault PATH```Gera `.obsidian-master/migration-proposal.md`: tabela `pasta -> cluster dominante ->area proposta`. Usuario revisa/edita.### Etapa 5 — Plan + approval (Wave 5)```bashmigrate.py plan --vault PATHmigrate.py approve --batch 1 [--batch all]```Gera registros em `migration_plan` em lotes de 20. Approval interativo por nota(`y/n/a/s`).### Etapa 6 — Execute + rollback (Wave 6)```bashmigrate.py apply --batch 1 [--batch all]migrate.py rollback --batch N # se precisar reverter```Aplica os renames dos `approved`, refatora wikilinks que quebrariam, emite eventos,e ao terminar cria `.obsidian-master/marker.json` com `migration_completed=true`.## Garantias- **Backup obrigatorio**: nunca move nada sem ter um `.backup-*` intacto- **Approval por lote**: usuario aprova 20 notas por vez, nunca o vault inteiro de um golpe- **Rollback disponivel**: cada batch aplicado pode ser revertido- **Opcao C**: descoberta de areas respeita o que ja existe; o kit adapta ao vault, nao o vault ao kit

Frequently asked questions