Back to Blog
Mate Benyovszky

Your Obsidian Vault Can Be Your Agent's Library, Not Its Runtime

Obsidian is optimized for humans, AgentPlaybooks for machines. Where the two overlap, what Obsidian does better, and how to publish skills from a vault to Claude Code, Cursor, and Codex without leaving Obsidian.

Your Obsidian Vault Can Be Your Agent's Library, Not Its Runtime

If you keep notes in Obsidian, you have probably already tried to make the vault do agent work. A Prompts/ folder. A note per skill. Maybe a filesystem MCP server pointed at the vault so Claude can read it. It half works, and it is hard to say exactly why.

Here is the seam, stated plainly: Obsidian is optimized for humans. AgentPlaybooks is optimized for machines. A vault is a superb library. It is not a runtime. Everything that feels almost-right about a vault-as-agent-brain setup traces back to that one line.

Nothing below asks you to move your notes.

The overlap is real

Both sides treat markdown with frontmatter as the primitive — an Obsidian note and a SKILL.md are physically the same kind of file. Both make the same promise about lock-in: your files, your folder, forever on one side; your agents stay yours on any platform on the other. Both end up as the place a team's reusable process knowledge accumulates.

That overlap is why the two compose almost for free, and it is also why people keep expecting one to replace the other.

What Obsidian is better at

Worth saying first, because it is true:

  • Writing and reading. The editor, backlinks, graph view, the mobile app.
  • Unstructured knowledge. You never need to know what a note is before you
start writing it. A skill is a contract, so you do.
  • Zero infrastructure. No account, no database, no network. For some people
that is the requirement, not a convenience.
  • A far larger plugin ecosystem and a much bigger community.
  • Years of personal notes. Agent memory is not built for this and should not
be.

If you work alone, on one machine, with one agent platform, and no API key is involved — a vault plus a filesystem MCP server is a genuinely sufficient setup. Adding a platform would be overhead. That is an honest recommendation, and it holds until your second machine, your first teammate, or your first credential shows up.

What a vault structurally cannot do

These are not missing features. They follow from what a folder of notes is:

Deploy to more than one agent platform. The same skill has to land in .claude/skills/, .cursor/skills/, .codex/skills/ plus a config.toml, .agents/skills/, and ~/.hermes/config.yaml — each with the correct layout, and with drift between the copies actually detected. A vault has no concept of a deployment target. apb sync does nothing else.

Hold a credential safely. This is the sharp one. The moment a vault-based AI setup needs an API key, that key goes in plaintext into .obsidian/plugins//data.json. From there into Sync. And into git history if the vault is versioned. AgentPlaybooks keeps the value encrypted and injects it server-side, so the plaintext never reaches the disk or the agent's context.

Let two agents write at once. A Canvas document takes an expectedVersion and returns HTTP 409 on a stale write, so the losing agent knows it lost. Two agents editing one note through Sync produce note (conflicted copy).md and nobody finds out until much later.

Express permissions. Sharing a vault shares all of it. There is no "this teammate may edit skills but not rotate secrets" in a folder.

Using both, today, with no plugin

apb push reads skills from any folder shaped as /SKILL.md. A vault folder can be exactly that shape:

MyVault/
  Skills/
    code-review/SKILL.md
    release-notes/SKILL.md

cd MyVault
apb push --apply

You write in Obsidian. Your teammates get those skills in whichever tool they use. Pull the other direction and shared skills arrive as plain markdown you can drop into the vault and link like any other note — so the project note can link to the skill that automates the project.

And when an agent finishes a long task, its Canvas document is markdown too. The agent writes where writing is safe and versioned; you read where reading is pleasant.

One rule keeps both clean

Vault for durable human knowledge. Playbook memory for machine state.

Decisions, meeting notes, research, half-formed ideas: vault. Working-tier scratch state, task graphs, run status, structured facts an agent reads back next session: playbook memory.

Break this rule in one direction and you get a polluted graph and a stream of sync conflicts. Break it in the other and you get a key-value store you cannot think in.

Try it against a vault you already have

Read-only, nothing is written:

apb doctor /path/to/MyVault

It reports Agent Skills spec violations, likely hard-coded credentials (line numbers only, never values), and definitions that have drifted between copies. Most people find at least one plaintext key they had forgotten about.

Then, when you want the prompts to actually work inside every agent tool you have installed:

apb sync /path/to/MyVault --apply

Your vault is untouched. Keep Obsidian.

The full comparison table, the interop recipes, and the memory-boundary rule live in the docs: Obsidian and AgentPlaybooks.

Share this article