Obsidian Skill: Let AI Agents Work Inside Your Vault Without Breaking Links

38,000+ downloads and 155 stars — obsidian by @steipete (Peter Steinberger, the same author behind the weather and gog skills) is the most-downloaded note management skill on ClawHub. It solves a problem that trips up everyone who tries to script Obsidian the naive way: how do you move or rename files without silently breaking every [[wikilink]] that points to them?

The Problem With Scripting Obsidian Directly

Obsidian stores everything as plain Markdown files in a folder. That makes it tempting to use ordinary file commands — mv, cp, rm — when you want to automate vault management.

The issue: Obsidian uses [[wikilinks]] to link between notes, and those links reference filenames. If you rename or move a file at the filesystem level without going through Obsidian's rename mechanism, every existing link to that file silently breaks. Obsidian won't warn you. Your knowledge graph degrades invisibly.

The right approach is to go through obsidian-cli — a command-line interface (originally by Yakitrak, recently superseded by Obsidian's own official CLI released in v1.12 in February 2026) — which hooks into Obsidian's URI handler and can perform "safe refactors" that update links across the vault.

Steipete's skill teaches Claude Code how to use this interface correctly: how to find your vault, how to choose between safe CLI operations and direct file edits, and how to avoid the common pitfalls.

How the Skill Works

Step 1: Find the Active Vault

Obsidian tracks all vaults in a JSON config file:

• macOS: ~/Library/Application Support/obsidian/obsidian.json
• Windows: %APPDATA%/obsidian/obsidian.json

The skill reads this file to locate vaults rather than guessing paths. This matters because most power users have multiple vaults (personal, work, iCloud-backed) and the active one can change.

# Print the default vault path
obsidian-cli print-default --path-only
 
# Or read the config directly if needed
cat ~/Library/Application\ Support/obsidian/obsidian.json

Step 2: Set a Default Vault

Once per setup, tell obsidian-cli which vault to use as default:

obsidian-cli set-default "My Vault"

The vault name is the folder name (the last segment of the path in the config file). After this, most commands work without needing to specify the vault every time.

Core Commands

Search Notes

Two search modes: by filename or by content:

# Search note filenames
obsidian-cli search "meeting notes"
 
# Search note content (shows matching lines + snippets)
obsidian-cli search-content "quarterly review"

search-content is particularly useful for AI-assisted research — "find all notes that mention project X" becomes a single command that returns context-rich snippets.

Create Notes

obsidian-cli create "Projects/New Research Note" --content "# Topic\n\nInitial thoughts..." --open

The create command uses Obsidian's URI handler, which means:

• The note appears in Obsidian immediately (no app restart)
• Folder path is created if it doesn't exist
• --open brings the note into focus in the Obsidian window

Caveat: don't create notes inside dot-folders (.something/) via URI — Obsidian may refuse to open them.

Move / Rename (The Key Feature)

# Safe move that updates all wikilinks in the vault
obsidian-cli move "Old Folder/Research Note" "New Folder/Research Note"

This is the reason the skill exists. A regular mv command at the filesystem level would move the file and silently break every [[Research Note]] reference in your vault. obsidian-cli move performs a safe refactor: it moves the file AND updates all [[wikilinks]] and common Markdown links that point to it.

For bulk reorganization scripts — moving hundreds of notes into a new folder structure — this is the only safe approach.

Delete

obsidian-cli delete "Old Notes/Outdated Research"

Removes the note. Does not automatically clean up dead links pointing to the deleted note, so use with care.

When to Use Direct File Edits vs obsidian-cli

The skill is explicit about this tradeoff:

For heavy content transformation — adding frontmatter to 500 notes, bulk find-replace, extracting data — direct file manipulation with Python scripts is faster. Obsidian will pick up the changes when you switch back to the app. Use the CLI for the structural operations that need link awareness.

Practical Workflows

Automated Research Note Collection

When doing research, your AI agent can create structured notes automatically:

# Create note with content in the right folder
obsidian-cli create "Research/AI/2026-03-08-topic" --content "$(cat research_notes.md)"

Combine with search-content to check if a topic has already been researched before creating a duplicate.

Vault Reorganization

Reorganizing a vault without breaking anything:

# Move all notes matching a pattern to a new folder
obsidian-cli move "Archive/2024/Q1 Notes" "Archive/2024/Q1/Notes"

The CLI handles all link updates. Run obsidian-cli search-content "Q1 Notes" before and after to verify nothing broke.

Daily Note Automation

# Create today's daily note if it doesn't exist
obsidian-cli create "Daily/2026-03-08" --content "# 2026-03-08\n\n## Tasks\n\n## Notes\n"

Integrate with your morning routine: a cron job creates the daily note before you sit down, pre-populated with your agenda from other systems.

Knowledge Base Maintenance

The combination of search-content + move + direct edits enables an AI agent to do meaningful vault maintenance: find notes that belong in a different folder based on their content, propose a reorganization, then execute the moves safely.

Considerations

• macOS-first design — The vault config path and obsidian-cli behavior are documented for macOS. Windows and Linux users have similar vault JSON files but path conventions differ slightly.
• Requires Obsidian to be installed — obsidian-cli create uses the obsidian:// URI handler, which requires the Obsidian app to be installed. Some operations work without Obsidian running; --open requires it to be running.
• obsidian-cli vs official CLI — The skill uses Yakitrak's community obsidian-cli (installable via brew). Obsidian's own official CLI (released in v1.12, February 2026) has a different interface. The skill's documentation refers to the community version; you may need to adapt commands if using the official one.
• No direct database access — Obsidian's search index is internal. search-content uses obsidian-cli's own search, which may differ from what you see in Obsidian's search UI.
• Single vault at a time — The skill's set-default approach works well for one primary vault but adds friction if you regularly switch between vaults.

How to Install

clawhub install obsidian

Requirement: obsidian-cli must be installed separately:

# macOS
brew install yakitrak/yakitrak/obsidian-cli
 
# Then set your default vault (once)
obsidian-cli set-default "Your Vault Name"

The skill includes setup verification — if obsidian-cli isn't found, it will tell you exactly what to install.

The Bigger Picture

The pattern here is important beyond Obsidian: every time an AI agent needs to interact with a local application's data, the right approach is to go through the application's sanctioned interface rather than directly manipulating its files. Obsidian's vault is a perfect example — it looks like a plain folder of Markdown files, and it is, but the application maintains metadata (link indexes, graph views, workspace state) that breaks when you work around it.

obsidian-cli is the interface the community built to solve this. Steipete's skill brings that interface into the AI agent workflow, with the reasoning about when to use it vs when direct edits are appropriate baked in.

The result: 38,000+ downloads from people who want AI automation that doesn't destroy their knowledge base.

View the skill on ClawHub: obsidian