How to use the Obsidian CLI Vault Control agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a request matches the skill's description. This skill is written for Obsidian, a note-taking app that stores notes as files in a folder called a vault.

With the skill installed, the agent can read notes, create notes, append text, search the vault, manage tasks, properties and tags, check backlinks, and work with daily notes. The agent does this by running the obsidian command in your terminal, so the app must be open.

Install the obsidian-cli skill

Download the ZIP for this skill from this page and unzip it. You can put the skill in one of two places. For all your projects, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

Before you rely on the skill, confirm the Obsidian CLI works by running obsidian help in a terminal. If the command is not found, the skill cannot run its commands.

• Requirement: Obsidian desktop app installed and open.
• Requirement: Obsidian CLI available on the command line.

Trigger the skill with natural requests

You do not need to name the skill. The skill's description covers requests to interact with your vault, manage notes, search vault content, run vault operations from the command line, or develop and debug plugins and themes. Ask in plain language and mention Obsidian or your vault so the agent knows where to look.

Good requests name the note or the action. For example, ask the agent to find notes that mention a topic, add a task to today's daily note, or set a status property on a named note.

• Search my Obsidian vault for notes that mention invoices and list the top 10.
• Add the task 'call the accountant' to my daily note.
• Set the status property to done on my Project Plan note.
• Show me the backlinks for my Reading List note.
• List the tags in my vault sorted by how often they are used.

Understand how the commands are written

Parameters take a value with an equals sign, and values with spaces are quoted. Flags are switches with no value. Many commands accept file (resolves like a wikilink, name only) or path (exact path from the vault root, such as folder/note.md). If you omit both, the active file is used. Commands target the most recently focused vault unless you give vault= first.

You will rarely type these yourself, but reading them helps you check what the agent plans to run.

• Use \n for a new line and \t for a tab in multiline content.
• Add --copy to any command to copy its output to the clipboard.
• Add silent to stop files from opening.
• Add total to list commands to get a count.

Use the skill for plugin and theme development

If you build Obsidian plugins or themes, the skill describes a develop-and-test loop. After a code change, the agent reloads the plugin, checks for errors, and then verifies the result with a screenshot or DOM inspection. It can also read console output for warnings.

The skill also covers running JavaScript in the app with eval, reading CSS values, and toggling mobile emulation. Run obsidian help to see further developer commands, including CDP and debugger controls, which the source does not describe in detail.

• Reload a plugin with plugin:reload id=your-plugin-id.
• Check errors with dev:errors.
• Capture a screenshot with dev:screenshot.
• Read errors in the console with dev:console level=error.

Safety notes before you run it

Commands write directly to your notes. The overwrite flag can replace existing content, so use a test vault or back up important notes before letting an agent edit them. Review what the agent proposes when the vault matters to you.

The skill runs scripts, so treat it like any code you install. It does not use the network, according to its listing. The eval command runs arbitrary JavaScript inside the app and can read or change anything the app can access. Do not use it in environments where that is unacceptable.

• Keep a backup or use a test vault for first runs.
• Avoid the overwrite flag unless you intend to replace content.
• Skip eval in sensitive environments.

Tips for getting reliable results

Mention the vault name if you have more than one open, since commands otherwise use the most recently focused vault. Name the note precisely, or give its path, so the agent does not act on the active file by accident.

If a command behaves unexpectedly, ask the agent to run obsidian help to see the current command list. The skill itself points to the official help page for full documentation.

• Name the vault when you have several.
• Give exact note names or paths.
• Ask the agent to show the command before running it if you want to review it.