Guide · Agent skill
How to use the Obsidian Vault Manager agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains how to install and use the obsidian agent skill, which teaches an AI agent to work with Obsidian vaults. Obsidian stores your notes as plain Markdown files in a folder on your computer, and this skill lets the agent find that folder, search notes, create new ones, and move or delete them through the obsidian-cli command-line tool. By the end you will know how to install the skill, ask for work in plain language, and check what the agent is doing to your files.
Obsidian Vault Managerspinabot/brigade · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the obsidian skill ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
- 2Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
- 3Install obsidian-cli. Install the tool with Homebrew using the formula yakitrak/yakitrak/obsidian-cli.
- 4Install Obsidian desktop. Make sure the Obsidian desktop app is installed, since create relies on its URI handler.
- 5Set a default vault. Run obsidian-cli set-default with your vault's folder name, then confirm with print-default.
- 6Ask in plain language. Describe the note task you want, naming the note or folder involved.
- 7Review before delete or move. Check the target path the agent plans to use before confirming a delete or move.
What is an agent skill, and what does the obsidian skill do?
An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for one kind of task. When the skill is installed, the agent can read those instructions and follow them when your request matches the task.
The obsidian skill covers Obsidian vaults. A vault is a normal folder on disk, and its notes are *.md files. With the skill, the agent can locate your active vault, search note names and note contents, create notes, and move or delete them using obsidian-cli.
- Find the active vault by reading Obsidian's config file, or by using a default vault you have set.
- Search note names with a query, or search inside notes to see matching snippets and lines.
- Create a new note at a path you choose, with optional content.
- Move or rename a note. Moving through obsidian-cli also updates [[wikilinks]] and common Markdown links across the vault, which a plain mv would not do.
- Delete a note at a given path.
Install the obsidian skill
Download the skill ZIP from this page and unzip it. For a personal install, place the obsidian folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.
The skill also depends on obsidian-cli. The listed install method uses Homebrew with the formula yakitrak/yakitrak/obsidian-cli, so Homebrew must be installed first.
brew install yakitrak/yakitrak/obsidian-cliSet up obsidian-cli and choose a default vault
Your computer may have several vaults, for example one in iCloud and one in Documents. Pick a default so the agent does not have to guess which one you mean.
Set the default vault using its folder name. You can then check the current default, with or without the path only.
- Set the default: obsidian-cli set-default "<vault-folder-name>"
- Check the default: obsidian-cli print-default, or obsidian-cli print-default --path-only for just the path.
obsidian-cli set-default "<vault-folder-name>"Ask the agent for note tasks in plain language
You do not need to type commands yourself. Describe what you want and the agent will pick the matching obsidian-cli action. Be specific about the note name or folder, because the skill tells the agent not to guess which vault or file you mean.
Typical requests include finding a note by title, searching for a phrase inside your notes, drafting a new note in a folder, or reorganising a folder and keeping existing links working.
- "Find my notes that mention the quarterly budget."
- "Search my Obsidian vault for notes with the title 'meeting'."
- "Create a note called Projects/Website redesign with a short outline."
- "Move Inbox/ideas to Archive/2024 ideas and keep the links working."
Understand what happens with create, move and delete
Create uses an Obsidian URI (obsidian://) to open the note, so the Obsidian desktop app must be installed and its URI handler must work. The skill also says Obsidian may refuse to create notes inside hidden dot-folders such as .something/, so avoid those paths.
Move is the safe way to rename or reorganise, because it updates links across the vault. Delete removes the note at the path you give, so review the target before confirming.
obsidian-cli create "Folder/New note" --content "..." --open
obsidian-cli move "old/path/note" "new/path/note"
obsidian-cli delete "path/note"Safety notes: scripts, file changes and network
This skill runs scripts, because obsidian-cli is a command-line tool that the agent calls. It does not use the network, according to the skill's listed details.
The skill includes delete and move commands that act on your real files, so keep a backup or use version control for important vaults. The skill also advises against hardcoding vault paths in scripts and against touching the .obsidian/ config folder from scripts.
- Back up or version your vault before bulk moves or deletes.
- Check the exact note path the agent plans to use before it deletes or moves anything.
- Leave .obsidian/ settings alone unless you know what you are changing.
- Config location documented in the skill is macOS-specific: ~/Library/Application Support/obsidian/obsidian.json.
Tips for better results
For simple edits, you can ask the agent to change a .md file directly, since Obsidian picks up changes made to the file. Use search and print-default first when a request is ambiguous, so the agent confirms the vault before acting.
Use folder paths in the note name when creating notes, such as Folder/New note, so the note lands where you expect.
- Set a default vault once instead of naming it in every request.
- Use search-content when you remember a phrase but not the note title.
- Prefer move over copying and deleting when reorganising, so links stay intact.
What people use it for
- Search across all notes for a phrase and collect the matching snippets into one summary.
- Draft a new note in a chosen folder with starting content, then open it in Obsidian.
- Rename or reorganise folders while keeping [[wikilinks]] and Markdown links working.
- Clean up old notes by moving them into an archive folder after you confirm the list.
- Script around a plain Markdown note collection, using obsidian-cli for search and move.
Frequently asked questions
How do I install the obsidian agent skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings, Capabilities, Skills.
Is the obsidian skill free, and what licence does it use?
The skill is listed under the MIT licence. This page does not list any price, so check the source repository for any terms beyond the licence.
What do I need to use the obsidian skill?
You need obsidian-cli, installed with Homebrew using yakitrak/yakitrak/obsidian-cli, and the Obsidian desktop app for the create command. The skill assumes an Obsidian vault already exists on disk.
Does the obsidian skill work on Windows or Linux?
The documented vault config location is macOS-specific, at ~/Library/Application Support/obsidian/obsidian.json. On other systems you would need to adjust that config path yourself.
Why does obsidian-cli move work better than mv for notes?
Moving a note with obsidian-cli updates [[wikilinks]] and common Markdown links across the vault. A plain mv only renames the file, so links to it can break.
Can the agent delete my notes by mistake?
The skill includes a delete command that acts on real files, so mistakes are possible. Back up or version your vault first and check the path before confirming.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose this skill if your notes live in Obsidian and you want an agent to search, draft, or reorganise them, especially when you need links kept intact during moves. Skip it if you do not use Obsidian, if you cannot risk files being moved or deleted, or if you are on a non-macOS system and are not ready to adjust the config path.
Download the skill