# Obsidian Librarian

> Esta skill deve ser usada quando o usuario diz "sincroniza o vault", "roda o bibliotecario", "atualiza o indice do Obsidian", "valida as notas que acabei de escrever", ou invoca /obsidian-master-kit:sync. Tambem e acionada automaticamente apos qualquer Write/Edit dentro de um vault obsidian-master-kit (via hook PostToolUse). Le o CLAUDE.md do vault como memoria, valida frontmatter, normaliza tags, garante wiki-link para o MOC da area, reescreve _INDEX.md vivo e reporta desvios que exigem decisao humana. NAO deleta conteudo humano. NAO edita o CLAUDE.md do vault.

- Skill: `melgarafael/obsidian-librarian` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add melgarafael/obsidian-librarian`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melgarafael/obsidian-librarian/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: melgarafael (https://skillmd.com/u/melgarafael)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/melgarafael/obsidian-librarian

---


# obsidian-librarian

Curador automatico do vault. Roda apos qualquer escrita, le a doutrina (`CLAUDE.md`
do vault), valida o que foi escrito, corrige o que e deterministico, e mantem o
`_INDEX.md` vivo.

## Quando usar

- Apos qualquer `Write` ou `Edit` em path dentro de um vault-master (disparo
  automatico via hook `post-vault-write.py`).
- Quando o usuario invoca `/obsidian-master-kit:sync`.
- Quando o usuario diz "atualiza o indice", "roda o bibliotecario", "sincroniza o
  vault".

## Quando **nao** usar

- Em paths fora de um vault-master (o hook protege, mas valide antes por seguranca).
- Se a ultima invocacao foi ha menos de 5 segundos — dedupe para evitar loops.

## Fluxo canonico

### Passo 1: Detecte o vault

Caminhe para cima a partir do arquivo modificado procurando `.obsidian-master/marker.json`.
Esse arquivo marca a raiz do vault. Se nao achar, aborta silenciosamente — nao e
vault-master.

### Passo 2: Leia a doutrina

Leia `<vault-root>/CLAUDE.md` inteiro. Dali voce extrai:

- Schema de frontmatter (campos obrigatorios, valores validos)
- Schema de tags (hierarquia canonica)
- Mapa de pastas (qual area cada pasta representa)
- Regras de linking (todo arquivo linka pelo menos para o MOC da area)

Essas sao regras locais do vault — podem divergir do default do kit se o humano
tiver editado.

### Passo 3: Invoque o script de indexacao

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/obsidian-librarian/scripts/update_index.py \
  --vault "<vault-root>" \
  [--since <ISO-timestamp>]
```

O script faz a parte deterministica:
- Walka o vault, le todo `.md`
- Parseia frontmatter (YAML)
- Valida campos obrigatorios (`created`, `updated`, `area`, `type`, `status`, `tags`)
- Normaliza tags (lowercase, sem `#` prefix no frontmatter)
- Atualiza campo `updated` com mtime do arquivo se estiver desatualizado
- Calcula estatisticas: contagem por area, MOCs ativos, notas orfas (sem wiki-link pra
  MOC), ultimas 10 adicoes
- Reescreve `<vault-root>/_INDEX.md`
- Atualiza `<vault-root>/.obsidian-master/last-sync.json`
- Reporta em stdout (JSON) as issues que precisam intervencao humana ou LLM

### Passo 4: Trate as issues reportadas

O script retorna JSON como:

```json
{
  "updated_index": true,
  "notes_scanned": 42,
  "orphans": ["02 - Pesquisas e Estudos/Ativas/Nota Solta.md"],
  "missing_frontmatter_fields": [
    {"file": "01 - Profissional/Projetos/X.md", "missing": ["status"]}
  ],
  "unknown_tags": [
    {"file": "02 - Pesquisas e Estudos/Ativas/Y.md", "tags": ["random/custom"]}
  ],
  "area_folder_mismatch": [],
  "last_sync": "2026-04-15T14:20:00"
}
```

Para cada categoria:

- **orphans**: consulte as referencias (em `references/linking-rules.md`) sobre como
  sugerir um MOC. Adicione linha em `## Relacionado` da nota apontando para o MOC da
  area. Se a nota nao cabe em nenhuma area existente, escale para o usuario.
- **missing_frontmatter_fields**: adicione os campos faltando seguindo os defaults
  de `references/frontmatter-schema.md`:
  - `status` ausente → `draft`
  - `tags` ausente → `[]`
  - `updated` ausente → data de hoje (mas o script ja faz isso)
  - **Nunca** chute `area` ou `type` — escale pro usuario.
- **unknown_tags**: compare com o schema em `CLAUDE.md` do vault. Se a tag nao bate,
  sugira a tag canonica mais proxima em 1 comentario para o usuario; nao altere sem
  permissao (tags podem ter significado semantico que o humano escolheu).
- **area_folder_mismatch**: a nota tem `area: pesquisa` mas esta em `01 - Profissional/`.
  **Nunca mova sem perguntar** — reporte ao usuario.

### Passo 5: Reporte curto ao usuario

Depois que o script rodou e voce tratou as issues, imprima 1 bloco conciso:

```
Librarian synced:
- 42 notas escaneadas, _INDEX.md atualizado
- 2 orfas linkadas ao MOC apropriado
- 1 frontmatter preenchido (status: draft)
- 1 tag desconhecida reportada (esperando sua decisao)
```

Mais que isso e ruido — a pessoa quer saber que o vault esta ok, nao um relatorio
de auditoria.

## Guardrails — regras inviolaveis

1. **Nunca deleta conteudo humano.** Nem 1 linha, nem 1 palavra.
2. **Nunca edita o `CLAUDE.md` do vault.** Territorio humano.
3. **Nunca move arquivos entre areas sem confirmacao.** Mismatch de area e um
   sinalizador, nao uma licenca pra mover.
4. **Nunca chuta campos semanticos** (`area`, `type`, `aliases`, conteudo do corpo).
5. Se o script falha, reporte o erro e pare. Nao tente "consertar" o vault na
   marra — prefere halt a corromper.

## Referencias bundled

- `references/obsidian-conventions.md` — convencoes oficiais do Obsidian destiladas
- `references/frontmatter-schema.md` — schema canonico do kit (fonte de verdade
  quando o vault nao tem override)
- `references/linking-rules.md` — regras de wiki-link, backlinks, aliases, MOCs