vault-refactor

Renames or moves Obsidian notes while rewriting all wikilink references across the vault.

2|Updated Apr 4, 2026
One-click install
npx skills add https://github.com/DoctorMozg/claude-pipelines --skill vault-refactor-doctormozg
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vault-refactor
Source: https://github.com/DoctorMozg/claude-pipelines/tree/main/plugins/mz-knowledge/skills/vault-refactor
Command: npx skills add https://github.com/DoctorMozg/claude-pipelines --skill vault-refactor-doctormozg

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Renaming or moving a note in an Obsidian vault silently breaks every wikilink pointing to it, including aliased links, heading and block references, embeds, Bases link() formulas, and quoted YAML frontmatter wikilinks. This Skill performs the rename safely by scanning all twelve reference forms, getting explicit user approval, and writing a rollback manifest before touching any file. ## Core Features & Use Cases - Full reference-graph scan: A read-only scanner agent enumerates every reference across all twelve Obsidian Flavored Markdown wikilink forms, with exact line, column, and proposed replacement. - Approval gate with rollback: Every affected file and before/after replacement is presented verbatim for approval, and a byte-for-byte rollback manifest with SHA-256 hashes is written before any vault file is modified. - Surgical edits and verification: A writer agent applies replacements via targeted Edit operations, the file is moved only after referrers are updated, and a post-write Grep confirms zero residual references. - Use Case: Rename a permanent note from "inbox-capture" to a claim-style title like "distributed-systems-favor-availability" and have every embed, alias, and Bases formula across the vault updated with a recoverable audit trail. ## Quick Start Rename the note "old-note" to "new-claim-title" in my Obsidian vault and update every wikilink reference to it.

Frequently Asked Questions about vault-refactor

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

FAQPage Schema
How do I rename an Obsidian note without breaking wikilinks?

Invoke the skill with the old and new note names separated by a double colon. It scans the vault for all twelve wikilink forms, shows every proposed replacement for approval, then applies targeted edits and verifies zero residual references remain.

How to move an Obsidian note to a different folder and update links?

Pass the new value as a vault-relative path instead of a bare basename. The skill rewrites all referrer links to the new path, creates the target folder if needed, and moves the file with an atomic filesystem mv only after referrers are updated.

Does it handle Obsidian Bases link() formulas and frontmatter wikilinks?

Yes. The scanner explicitly covers Bases link() formulas with and without display text, plus quoted YAML frontmatter wikilinks, alongside bare, aliased, heading, block, and embed forms. These forms are treated as mandatory because they fail silently if missed.

Can I undo a vault rename if something goes wrong?

Yes. A rollback manifest capturing every target file's original byte-for-byte content and SHA-256 hash is written before any vault file is modified. On partial failure the skill halts, prints the manifest path, and lists modified files for manual recovery.

When should I not use this vault refactoring approach?

Do not use it for creating new notes, deleting notes, editing note body content, or bulk orphan-link cleanup. It assumes the note continues to exist under a new name and only rewrites references tied to that rename or move.