How do I install the Obsidian skill?

Run npx skillmds@latest add bdambrosio/obsidian in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Obsidian safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Obsidian?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Obsidian free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Obsidian?

bdambrosio (@bdambrosio) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Obsidian by bdambrosio — Agent Skill

Name: Obsidian
Author: bdambrosio

Obsidian

Read, search, write, and list notes in the user's Obsidian vault. You can READ and SEARCH the whole vault — the user's own notes, web clippings, everything. You can only WRITE inside your own area (CW/<your name>/); any path you give for a write is placed there, so you can never overwrite the user's notes. The write observation tells you the actual path written — use that path to read it back. Multi-action — set `action` first, then provide the args required by that action.

bdambrosio 1145e6d 4 files · 38.5 KB Updated Sep 17, 2026

File contents

obsidian

Access the user's Obsidian vault via the Local REST API plugin.

Actions

read — read a single file. Needs path. Returns the file's markdown content. Whole vault in scope.
search — find notes by query. Needs query. Filename matches first, then content matches. Whole vault in scope.
write — create or overwrite a file inside your own area. Needs path and content. Optional frontmatter prepended as YAML.
list — list directory contents. Needs path (directory, e.g. "KnowledgeBases/"). Whole vault in scope.

Dated paths

A path may contain {today}, which is replaced with the current date in YYYY-MM-DD form before the vault is touched — Security/{today}-patrol.md becomes Security/2026-08-14-patrol.md. Pass the token literally; don't substitute the date yourself. It works for every action, so reading back today's note uses the same path you wrote it with. For any other date, write it out in full.

Write scope

Writes are fenced to CW/<agent-name>/. The path you supply is interpreted relative to that area: asking to write Security/patrol.md as Sentinel puts the note at CW/Sentinel/Security/patrol.md. This is not an error and needs no special path prefix from you — just write where you mean to, and read the returned path to know where it landed.

You cannot write outside your own area, including into another agent's. A path naming somewhere else in the vault nests under your area rather than reaching it. To get something to another agent, message them directly instead of leaving it in the vault.

Required environment

OBSIDIAN_URL (default http://127.0.0.1:27123) — Local REST API endpoint
OBSIDIAN_API_KEY — API key for the Local REST API plugin

Examples

{"thought": "look up the transformers note", "tool": "obsidian", "action": "read", "path": "KnowledgeBases/Transformers/_index.md"}

{"thought": "search for notes about attention mechanisms", "tool": "obsidian", "action": "search", "query": "attention mechanism"}

{"thought": "save the synthesis from the previous step", "tool": "obsidian", "action": "write", "path": "Clippings/2026-05-21-synthesis.md", "content": "$step2"}

{"thought": "see what's in the AI knowledge base", "tool": "obsidian", "action": "list", "path": "KnowledgeBases/AI/"}

Notes

Large content is best passed via a $stepN binding rather than inlined into the action — keeps the tool call small.
write is destructive within your own area (overwrites if the file exists there). Read first if you want to preserve existing content.
Note names are preserved exactly on read; spaces in a filename are normal and need no escaping. Names of files you create have spaces replaced with underscores.

---name: obsidiandescription: Read, search, write, and list notes in the user's Obsidian vault. You can READ and SEARCH the whole vault — the user's own notes, web clippings, everything. You can only WRITE inside your own area (CW/<your name>/); any path you give for a write is placed there, so you can never overwrite the user's notes. The write observation tells you the actual path written — use that path to read it back. Multi-action — set `action` first, then provide the args required by that action.---# obsidianAccess the user's Obsidian vault via the Local REST API plugin.## Actions- **`read`** — read a single file. Needs `path`. Returns the file's markdown content. Whole vault in scope.- **`search`** — find notes by query. Needs `query`. Filename matches first, then content matches. Whole vault in scope.- **`write`** — create or overwrite a file **inside your own area**. Needs `path` and `content`. Optional `frontmatter` prepended as YAML.- **`list`** — list directory contents. Needs `path` (directory, e.g. `"KnowledgeBases/"`). Whole vault in scope.## Dated pathsA path may contain `{today}`, which is replaced with the current date in`YYYY-MM-DD` form before the vault is touched — `Security/{today}-patrol.md`becomes `Security/2026-08-14-patrol.md`. Pass the token literally; don'tsubstitute the date yourself. It works for every action, so reading backtoday's note uses the same path you wrote it with. For any other date, writeit out in full.## Write scopeWrites are fenced to `CW/<agent-name>/`. The path you supply is interpretedrelative to that area: asking to write `Security/patrol.md` as Sentinel putsthe note at `CW/Sentinel/Security/patrol.md`. This is not an error and needsno special path prefix from you — just write where you mean to, and read thereturned path to know where it landed.You cannot write outside your own area, including into another agent's. Apath naming somewhere else in the vault nests under your area rather thanreaching it. To get something to another agent, message them directlyinstead of leaving it in the vault.## Required environment- `OBSIDIAN_URL` (default `http://127.0.0.1:27123`) — Local REST API endpoint- `OBSIDIAN_API_KEY` — API key for the Local REST API plugin## Examples```json{"thought": "look up the transformers note", "tool": "obsidian", "action": "read", "path": "KnowledgeBases/Transformers/_index.md"}``````json{"thought": "search for notes about attention mechanisms", "tool": "obsidian", "action": "search", "query": "attention mechanism"}``````json{"thought": "save the synthesis from the previous step", "tool": "obsidian", "action": "write", "path": "Clippings/2026-05-21-synthesis.md", "content": "$step2"}``````json{"thought": "see what's in the AI knowledge base", "tool": "obsidian", "action": "list", "path": "KnowledgeBases/AI/"}```## Notes- Large content is best passed via a `$stepN` binding rather than inlined into the action — keeps the tool call small.- `write` is destructive **within your own area** (overwrites if the file exists there). Read first if you want to preserve existing content.- Note names are preserved exactly on read; spaces in a filename are normal and need no escaping. Names of files you *create* have spaces replaced with underscores.

Frequently asked questions