Read, Search, Create, and Edit Notes in Your Obsidian Vault with Hermes Agent

The Obsidian skill for Hermes Agent lets you work with a local Obsidian vault using file tools instead of shell commands. You can read, search, create, append, and edit markdown notes, and add wikilinks. This is useful when you want the agent to manage your notes without leaving the safety of structured file operations.

What it does

This skill gives the agent the ability to interact with an Obsidian vault as a filesystem. It uses read_file, write_file, patch, and search_files to handle notes. The agent can list notes, search their contents, create new ones, append to existing ones, and make targeted edits. It also understands the [[Note Name]] wikilink syntax for linking notes.

Before you start

• The vault path must be known. The skill uses the OBSIDIAN_VAULT_PATH environment variable, which can be set in ${HERMES_HOME:-~/.hermes}/.env. If that variable is unset, the fallback path is ~/Documents/Obsidian Vault.
• File tools do not expand shell variables. Do not pass paths containing $OBSIDIAN_VAULT_PATH to read_file, write_file, patch, or search_files. Resolve the vault path first and pass a concrete absolute path.
• Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.
• If the vault path is unknown, you can use terminal to resolve OBSIDIAN_VAULT_PATH or check whether the fallback path exists. Once the path is known, switch back to file tools.
• The skill is bundled with Hermes Agent and works on linux, macos, and windows.

Read a note

Use read_file with the resolved absolute path to the note. Prefer this over cat because it provides line numbers and pagination.

List notes

Use search_files with target: "files" and the resolved vault path. Prefer this over find or ls.

• To list all markdown notes, use pattern: "*.md" under the vault path.
• To list a subfolder, search under that subfolder's absolute path.

Search

Use search_files for both filename and content searches. Prefer this over grep, find, or ls.

• For filenames, use search_files with target: "files" and a filename pattern.
• For note contents, use search_files with target: "content", the content regex as pattern, and file_glob: "*.md" when you want to restrict matches to markdown notes.

Create a note

Use write_file with the resolved absolute path and the full markdown content. Prefer this over shell heredocs or echo because it avoids shell quoting issues and returns structured results.

Append to a note

Prefer a native file-tool workflow when it is not awkward:

• Read the target note with read_file.
• Use patch for an anchored append when there is stable context, such as adding a section after an existing heading or appending before a known trailing block.
• Use write_file when rewriting the whole note is clearer than constructing a fragile patch.

For an anchored append with patch, replace the anchor with the anchor plus the new content.

For a simple append with no stable context, terminal is acceptable if it is the clearest safe option.

Targeted edits

Use patch for focused note changes when the current content gives you stable context. Prefer this over shell text rewriting.

Wikilinks

Obsidian links notes with [[Note Name]] syntax. When creating notes, use these to link related content.

When not to use it

This skill is for filesystem-first Obsidian vault work. If you need to interact with Obsidian's plugin API, sync service, or any feature that requires the Obsidian application to be running, this skill will not help. It treats the vault as a plain directory of markdown files.

Limits and gotchas

• File tools do not expand shell variables. Always resolve OBSIDIAN_VAULT_PATH to an absolute path before passing it to file tools.
• Vault paths with spaces are fine for file tools but can cause issues in shell commands. Stick with file tools.
• The patch operation requires stable context in the note. If the note content changes frequently, write_file may be safer.
• The skill does not handle Obsidian-specific features like templates, daily notes, or graph view.

What pairs with this

This skill works well with other note-taking skills in Hermes Agent, such as the generic note-taking skill for plain markdown files. For more complex workflows, consider combining it with the terminal skill for initial vault path discovery.