homelabstack/.agents/skills/vault/SKILL.md

name, description

name	description
vault	Read and write notes in ginnoir's self-hosted Obsidian vault via the Obsidian MCP server. Use when loading persistent context for a session, saving new context, writing a note, or querying vault contents. The vault is the canonical persistent-context store across Codex sessions.

vault

Obsidian vault accessed via the mcp__obsidian__* MCP tools. Do not attempt to connect to CouchDB directly — use MCP only.

The MCP server is configured in ~/.mcp.json and is available in every Codex session. If the tools are listed as deferred, load them with ToolSearch before calling.

Core tools

Tool	Use
mcp__obsidian__vault_list	List files/dirs in a directory (omit path for vault root)
mcp__obsidian__vault_read	Read a file's full content + metadata (tags, frontmatter, links, backlinks)
mcp__obsidian__vault_write	Create or overwrite a file
mcp__obsidian__vault_patch	Append or patch a section without a full rewrite
mcp__obsidian__vault_delete	Delete a file
mcp__obsidian__vault_move	Move or rename a file
mcp__obsidian__search_simple	Full-text search across the vault
mcp__obsidian__search_query	Advanced query search
mcp__obsidian__tag_list	List all tags

Load context at session start

1. mcp__obsidian__vault_read  path="Codex/Context.md"
2. Follow [[wikilinks]] to read specific notes as needed

Codex/Context.md is the master index. It links to all other context notes under Codex/.

Read a note

mcp__obsidian__vault_read  path="Codex/Homelab.md"

Returns: content (full markdown), tags, frontmatter, links, backlinks, stat.

To read only a section:

mcp__obsidian__vault_read  path="Codex/Services.md"  targetType="heading"  target="BookStack"

Write a note

mcp__obsidian__vault_write  path="Codex/MyNote.md"  content="# Title\n\nContent here."

Creates parent directories automatically. Overwrites without warning.

Append to a note

mcp__obsidian__vault_patch  path="Codex/Context.md"  ...

Use vault_patch when adding a section to an existing note to avoid rewriting the whole file.

Search the vault

mcp__obsidian__search_simple  query="portainer env vars"

Vault structure

Codex/
  Context.md       — master index, session start guide, quick nav
  Homelab.md       — topology, stacks, networks, paths
  Deploy.md        — deployment channels
  SSH.md           — SSH ops, container management
  Portainer.md     — env interpolation gotcha, new stack registration
  Services.md      — per-service quirks (BookStack, Caddy, secrets policy)
  ROM Library.md   — RomM, igir, Pokémon romhacks, EmuDeck tree
  Monitoring.md    — Uptime Kuma v2 socket technique
  Vault.md         — this stack's infrastructure, MCP access
testing.md         — original connectivity test note
Pokémon ROM Hacks/   — Pokémon romhack KB in the live vault; catalog + build
                       scripts live in the standalone Documents\pokemon repo

Load tool schemas (if deferred)

If mcp__obsidian__vault_read is not yet callable, run:

ToolSearch  query="select:mcp__obsidian__vault_list,mcp__obsidian__vault_read,mcp__obsidian__vault_write"