Agent Skills: Obsidian Vault Manager

Obsidian Vault Manager

Prerequisites

Before performing vault operations:

1. Verify obsidian CLI is installed:

   obsidian --version
   

   The CLI is the native obsidian binary that ships with the Obsidian desktop app — not a separate npm package.

2. List available vaults:

   obsidian vaults
   

3. Get vault path:

   obsidian vault "<name>" info=path
   

Overview

Use obsidian for vault operations that touch links or structure. For creating notes with substantial content (multi-line, frontmatter, etc.), use the Write tool directly after locating the vault path — the CLI's create command strips multi-line content when \n escapes are used.

Quick Reference

| Task | Command | Notes | |------|---------|-------| | List vaults | obsidian vaults | Always run first | | Vault info | obsidian vault "<name>" | Name, path, file count | | Vault path | obsidian vault "<name>" info=path | Path only, good for scripting | | List folders | obsidian "vault=<name>" folders | Quote vault name if it has spaces | | Read note | obsidian "vault=<name>" read "<note name>" | Reads by name (fuzzy) | | Create note | obsidian "vault=<name>" create path="folder/name.md" content="$CONTENT" | Use printf to build $CONTENT for multi-line | | Overwrite note | obsidian "vault=<name>" create path="..." content="$CONTENT" overwrite | | | Append to note | obsidian "vault=<name>" append path="<path>" content="<text>" | | | Move note | obsidian "vault=<name>" move path="old.md" newpath="new.md" | Auto-updates all links | | Search content | obsidian "vault=<name>" search query="<term>" [path=<folder>] [format=json] | | | Daily note | obsidian "vault=<name>" daily | Create/open today's note |

See also:

• Complete obsidian Command Reference - All commands with flags and advanced usage
• Obsidian Syntax Reference - Wiki-links, tags, frontmatter, and markdown syntax
• Note Templates - Daily note, project, and meeting templates

Core Workflows

Step 1 — Find the Vault

# List vaults to confirm the name
obsidian vaults

# Get full info (name, path, file count)
obsidian vault "<name>"

# Get just the path (useful for scripting)
VAULT_PATH=$(obsidian vault "<name>" info=path)

Step 2 — Explore Structure

# List folders
obsidian "vault=<name>" folders

# Search for existing notes
obsidian "vault=<name>" search query="<topic>" path=<folder> format=json

Step 3 — Create Notes with Rich Content

Use printf to build the content variable — this correctly handles newlines and multi-line content including frontmatter:

CONTENT=$(printf '---\ntags:\n  - til\nindex: "[[Today I learned]]"\n---\n## Heading\n\nContent here.')
obsidian "vault=<name>" create path="til/2026-04-27 My Note.md" content="$CONTENT"

Look at an existing note first to match local formatting conventions (tag names, frontmatter fields, index backlinks, etc.):

obsidian "vault=<name>" read "<existing note name>"

Moving/Reorganizing Notes

# ✅ CORRECT: Auto-updates all links
obsidian "vault=<name>" move path="Random Notes/Design.md" newpath="Projects/Design.md"

# ❌ WRONG: Breaks all links to this note
mv "vault/Random Notes/Design.md" "vault/Projects/Design.md"

Common Mistakes

| Mistake | Why Wrong | Fix | |---------|-----------|-----| | Using obsidian-cli | That's a different npm package — the tool is obsidian | Use obsidian | | Using --flags syntax | The CLI uses key=value positional args, not --flags | Use key=value format | | create with \n in double-quoted string | Escapes get stripped, content truncated | Use printf to build a $CONTENT variable | | Using mv to move notes | Breaks all [[wiki-links]] to that note | Use obsidian move | | Not checking existing note format | Each vault has different tagging/frontmatter conventions | Read an existing note first | | Using absolute paths in wiki-links | Breaks when vault moves | Use vault-relative paths |

When to Use Standard Tools

• Bulk content editing: Use Edit after reading with obsidian read
• Complex search patterns: Use Grep directly on the vault path (use obsidian vault "<name>" info=path to get it)

Always preserve:

• Frontmatter (YAML between ---)
• Obsidian link syntax [[Note]]
• Tag syntax #tag-name
• Markdown structure

Success Criteria

Vault operations succeed when:

• All [[wiki-links]] remain valid after moves
• Notes created in correct vault location with full content intact
• Formatting matches existing notes in the same folder
• No broken links or orphaned notes