Wiki Lint: encontre links quebrados e órfãos sem alterar o vault

ANÁLISE EDITORIAL

Um vault pode abrir normalmente no Obsidian e ainda esconder links quebrados, páginas órfãs, metadados incompletos e índices que apontam para arquivos removidos. Wiki Lint foi criada para transformar esse tipo de revisão em uma inspeção determinística. Ela percorre a estrutura autorizada, devolve caminhos, linhas, alvos e categorias, mas não tenta consertar nada durante a auditoria.

Essa separação importa. Encontrar uma nota órfã não prova que ela deve ser apagada. Encontrar dois arquivos com o mesmo nome não autoriza renomear nenhum deles. A Skill orienta o agente a tratar o relatório como evidência para uma decisão posterior, com reparos revisados em outra operação.

O que esta Skill faz

A Wiki Lint no commit auditado conduz uma verificação somente leitura de uma wiki em Obsidian. O motor reconhece wikilinks, embeds, links Markdown, aliases, fragmentos de títulos e blocos, além de ignorar links aparentes dentro de trechos de código.

O resultado pode apontar links inexistentes ou ambíguos, páginas órfãs, nomes de arquivo duplicados, frontmatter incompleto, seções vazias, entradas antigas de índice, erros de leitura e inconsistências nos registros de procedência do próprio produto. O relatório também informa contagens. Ele não faz revisão semântica do texto, não detecta toda contradição possível e não avalia a qualidade da escrita.

Para quem serve

A Skill serve a pessoas e equipes que mantêm vaults extensos, bases de conhecimento em Markdown, wikis de pesquisa ou conjuntos de notas alimentados por agentes. Ela é útil antes de uma migração, depois de um lote de ingestão, durante a manutenção de índices ou quando a navegação começou a produzir páginas vazias e resultados ambíguos.

Ela não substitui o funcionamento de links do Obsidian, uma revisão editorial nem a leitura humana da arquitetura do vault. O linter observa regras implementadas pelo projeto. Uma nota isolada pode ser um rascunho legítimo, e um campo ausente pode ser aceitável fora do esquema adotado.

Origem, adoção e versões

A curadoria fixou o repositório AgriciDaniel/claude-obsidian no commit 32ac5a02c4e082e4a5628ca810776375e134708e. Na consulta de 14 de setembro de 2026, o repositório tinha 14.891 estrelas e 1.479 forks, não estava arquivado e declarava licença MIT.

A Skill não traz número de versão próprio no frontmatter. O CHANGELOG fixado registra a versão 2.2.0 do produto em 10 de setembro de 2026. O módulo de lint declara motor 1.1.1. Esses números descrevem camadas diferentes, por isso não são apresentados como uma única versão da Skill.

Por que ela não duplica as outras Skills de Obsidian

O catálogo já contém Skills para sintaxe de Markdown, Bases, Canvas e operação por CLI. Wiki Lint tem outra finalidade: produzir um diagnóstico repetível sem gravar no vault. Ela não cria notas, não corrige propriedades, não reorganiza pastas, não atualiza um Canvas e não executa ações genéricas no aplicativo.

O contrato do projeto também separa lint de reparo. A correção exige uma operação própria, leitura atual dos alvos, hashes esperados, prévia do pacote de mudanças e aplicação depois da revisão. Essa fronteira foi decisiva para a entrada no catálogo.

Compatibilidade e pré-requisitos

O núcleo portátil requer Python 3.11 ou superior. O Obsidian é necessário para a experiência visual, mas as notas continuam sendo Markdown. O README oficial de requisitos informa que inspeções somente leitura e operações de prévia funcionam no Windows nativo. Escritas do produto exigem WSL e falham de modo fechado fora dele.

Para Claude Code, o caminho de plugin requer uma versão atual compatível com os hooks usados pelo projeto. Codex, OpenCode, Gemini e ZCode usam a superfície portátil de Agent Skills. Bash é exigido pelos scripts de configuração e por testes shell, não pelo algoritmo de lint executado diretamente pelo Python.

O formato de Skill segue a especificação pública de Agent Skills. Compatibilidade com o formato não garante que todo host trate comandos, instalação e permissões da mesma forma. Confirme o diretório de descoberta e o interpretador antes de apontar para um vault real.

Instalação com a origem separada do vault

O projeto recomenda clonar o produto em uma pasta e manter o vault do usuário em outra. Essa distinção evita tratar o checkout do código como base de conhecimento pessoal. A sequência oficial começa assim:

git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

Depois de revisar o commit aprovado, use a guia oficial de instalação para criar ou adotar um vault. Inicialização, adoção e instalação de links são operações que escrevem. Confira a prévia e o hash de aprovação antes de aplicar.

Para Codex, o README documenta uma prévia e uma aplicação separadas:

bash scripts/setup-multi-agent.sh --host codex
bash scripts/setup-multi-agent.sh --host codex --apply

Esses comandos podem criar links de descoberta no ambiente. Não os execute em uma máquina compartilhada sem conferir os destinos. O ZIP desta página não contém o script de configuração nem o núcleo Python.

Primeiro uso somente leitura

Resolva primeiro o caminho do produto e o vault que deve ser inspecionado. Não derive o vault do diretório onde a Skill foi instalada. Com o núcleo oficial presente, um primeiro comando em JSON fica assim:

PRODUCT_ROOT=/caminho/para/claude-obsidian
CORE="$PRODUCT_ROOT/scripts/claude-obsidian.py"
VAULT=/caminho/para/o/vault
python3 "$CORE" lint --vault "$VAULT"

Para leitura humana, acrescente --format markdown. A saída vai para stdout. Não redirecione automaticamente o texto para dentro do vault, porque isso criaria um novo arquivo que poderia alterar a próxima contagem. O comando oficial de lint chama o motor e apenas imprime o relatório.

Escopo, exclusões e modo estrito

O parâmetro repetível --exclude GLOB remove caminhos específicos da varredura de páginas, links, órfãos, frontmatter, seções vazias e índices. Ele é útil para uma pasta de rascunhos temporários, mas pode esconder defeitos reais. Registre cada exclusão e revise-a periodicamente.

python3 "$CORE" lint --vault "$VAULT" \
  --format markdown \
  --exclude "wiki/scratchpad/*"

Use --strict somente quando a automação deve sair com código 1 ao encontrar problemas. O modo estrito não grava nem corrige arquivos, mas pode interromper um pipeline. A orientação da própria Skill mantém essa diferença explícita.

Como interpretar o relatório

Comece por navegação quebrada. Um link morto traz caminho, linha, destino e motivo. Um alvo ambíguo costuma significar que o nome curto pode resolver para mais de um arquivo, situação em que um caminho qualificado é mais seguro. Não escolha automaticamente um dos candidatos.

Depois observe metadados e manutenção. O motor verifica campos esperados pelo esquema do projeto, como título, tipo, estado e datas. Uma seção vazia pode indicar um template incompleto, enquanto uma entrada antiga de índice pode apontar para uma nota movida. A implementação do motor é a fonte para as categorias realmente calculadas.

Trate uma allowlist como política, não como prova de existência. Ela pode suprimir um destino conhecido e intencional, mas não transforma o link em válido. Preserve no relatório a diferença entre problemas ativos e itens aceitos temporariamente.

Resultado esperado

O resultado esperado é um relatório JSON ou Markdown com resumo e achados reproduzíveis. Em uma execução editorial controlada sobre um fixture local, o motor informou suas categorias e a comparação dos hashes antes e depois confirmou que nenhum arquivo do vault de teste foi alterado. Isso verifica o comportamento observado nesse fixture, não certifica todo ambiente possível.

O projeto mantém testes específicos do motor para links, fragments, aliases, arquivos ignorados, exclusões, frontmatter e procedência. Testes do mantenedor ajudam a revisar comportamento, mas não substituem uma cópia, um escopo explícito e validação no sistema onde o vault será usado.

Permissões e riscos

• Leitura local: o linter precisa ler caminhos, nomes, conteúdo Markdown, propriedades, índices e registros de procedência dentro do vault selecionado.
• Dados sensíveis: títulos, links e frontmatter podem revelar clientes, projetos, pessoas, fontes, datas e estrutura interna.
• Saída: o relatório pode repetir caminhos e alvos. Não o publique nem envie a terceiros sem revisão.
• Exclusões: padrões amplos demais podem ocultar páginas relevantes e produzir uma impressão incompleta de saúde.
• Reparo: a Skill não autoriza renomear, excluir, mover ou reescrever notas. Essas ações pertencem a outro fluxo.

O guia oficial de propriedades do Obsidian ajuda a entender o que o aplicativo aceita, enquanto o linter aplica o contrato mais específico do projeto. Uma diferença entre os dois deve ser analisada antes de qualquer correção em lote.

Erros comuns e como corrigir

O núcleo não foi encontrado: confira se PRODUCT_ROOT aponta para o checkout do produto, não para o vault, e se scripts/claude-obsidian.py existe no commit aprovado.

O Python não atende ao requisito: confirme a versão com python3 --version. No Windows, o alias da Microsoft Store pode não apontar para a instalação desejada. Siga o guia oficial para Windows e WSL.

A contagem de órfãos parece alta: confira se índices e páginas de entrada fazem parte da convenção adotada. Um órfão pode ser intencional. Não converta contagem em exclusão automática.

Um link válido apareceu como ambíguo: verifique se existem arquivos com o mesmo basename. Use caminho explícito quando houver mais de um candidato. O motor também consulta arquivos .gitignore internos ao vault sem chamar o processo Git.

O pipeline falhou com achados: remova --strict durante a exploração ou trate o código 1 como presença de problemas, não como falha do executável.

O relatório mudou depois de ser salvo: não grave a saída dentro da árvore inspecionada. Salve fora do vault ou mantenha o resultado em stdout.

Reparo é uma operação separada

Depois do lint, selecione achados específicos. Releia cada arquivo, calcule o hash atual, prepare apenas as alterações aprovadas e mostre os caminhos afetados. O projeto usa um pacote transacional com prévia e hash de aprovação para evitar que um reparo antigo seja aplicado sobre um arquivo que já mudou.

Não transforme uma lista de links mortos em uma busca e substituição global. Um destino pode ter sido renomeado, dividido, arquivado ou removido de propósito. A correção precisa preservar intenção, backlinks, aliases e estrutura do índice.

Versão, licença e pacote auditado

O pacote local contém três arquivos textuais: SKILL.md, LICENSE e ORIGEM.md. Seu SHA-256 é bb137095c2bf3092f1e17399db518354b14260c0a91e0e32ea157e3c72c816cf. O arquivo da Skill e a licença preservam os hashes do commit fixado; o registro de origem foi acrescentado pelo Bastidores.

A licença MIT da origem permite redistribuição sob suas condições. O aviso foi mantido. Licença aberta não certifica segurança, compatibilidade, ausência de bugs nem adequação ao esquema do seu vault.

Limites do download local

O ZIP não inclui o núcleo claude_obsidian, o motor Python, scripts, hooks, instaladores, Bash, Git, Python, Obsidian, plugins, dependências, configurações, vaults, notas, anexos, índices, allowlists, credenciais, caches, resultados ou relatórios. Ele é uma cópia documental para auditoria e comparação.

Para uso funcional, obtenha o produto completo pela origem oficial, fixe commit ou release e revise os arquivos executados. O botão do repositório é separado do download local justamente porque o pacote não pretende simular uma instalação pronta.

Checklist antes de usar

1. Defina o vault exato e faça uma cópia ou snapshot antes de qualquer reparo posterior.
2. Separe o checkout do produto da pasta de notas do usuário.
3. Fixe commit ou release e confira Python 3.11 ou superior.
4. Execute primeiro sem --strict e mantenha a saída fora do vault.
5. Revise exclusões e allowlists como política temporária.
6. Preserve caminhos, linhas, alvos e categorias ao discutir os achados.
7. Não trate órfão, duplicata ou campo ausente como autorização de apagar.
8. Prepare reparos em outra operação, com hashes atuais e revisão humana.

Fontes oficiais consultadas

• Repositório oficial claude-obsidian.
• Wiki Lint SKILL.md no commit auditado.
• README e requisitos do produto.
• CHANGELOG 2.2.0.
• Motor determinístico de lint.
• Testes do motor de lint.
• Matriz e orientação para Windows e WSL.
• Especificação Agent Skills.

Se esta for sua primeira automação de vault, consulte o catálogo de Skills do Bastidores da IA. Comece por leitura e diagnóstico, mantenha o relatório fora da base e aprove separadamente cada reparo que alterar notas.