vault-doctor

Diagnose and repair unresolved links, missing frontmatter, and orphan notes in Obsidian vaults.

Updated Nov 1, 2024
One-click install
npx skills add https://github.com/mlorentedev/dotfiles --skill vault-doctor-mlorentedev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vault-doctor
Source: https://github.com/mlorentedev/dotfiles/tree/main/harness/skills/vault-doctor
Command: npx skills add https://github.com/mlorentedev/dotfiles --skill vault-doctor-mlorentedev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Obsidian knowledge vaults accumulate structural debt over time: broken wikilinks, notes missing required frontmatter fields, and orphaned content disconnected from the rest of the graph. This Skill diagnoses those issues, prioritizes them by severity, and fixes them systematically without risking data loss. ## Core Features & Use Cases - Structural Diagnosis: Runs vault health checks via Hive MCP and obs-cli to collect unresolved links, frontmatter violations, orphan notes, and dead-end notes. - Severity-Based Repair: Prioritizes fixes (HIGH: broken links and missing type/status; MEDIUM: orphans and missing ids; LOW: dead ends) and resolves them one tier at a time. - Safe Frontmatter Injection: Infers id, type, and status from file location and content, adding only missing fields without overwriting existing values. - Use Case: After a vault_health report flags 22 unresolved links and 5 orphan notes, run this Skill to get a severity report, resolve link targets via search, inject missing frontmatter in bulk, and connect or archive orphans with user confirmation. ## Quick Start Ask the assistant to run a vault doctor diagnosis on your Obsidian vault and fix all high-severity structural issues.

Frequently Asked Questions about vault-doctor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix broken wikilinks in an Obsidian vault?

Run a diagnosis to collect unresolved links, then search the vault for candidate target notes with similar names. Apply confirmed matches via vault_patch, create stub notes for missing concepts, or remove stale links after user confirmation.

How to find orphan notes in Obsidian?

Use the obs-cli orphans command when the Obsidian GUI is running, or query the vault through Hive MCP headlessly. Orphan notes have no incoming links and can be connected to related notes or moved to an archive folder.

Does vault maintenance work without the Obsidian GUI running?

Yes, Hive MCP tools like vault_health, vault_search, and vault_patch work headlessly and are always available. obs-cli commands that require the GUI exit with code 2, and the workflow degrades gracefully to MCP-only diagnostics.

Will fixing frontmatter overwrite my existing metadata?

No, the repair process only adds missing fields such as id, type, or status. Existing frontmatter values are preserved, and no content is deleted or links removed without explicit user confirmation.

What frontmatter fields does an Obsidian note need?

Notes should include id, type, and status fields. The id is derived from the filename slug, type is inferred from the directory location, and status defaults to active unless the content suggests otherwise.