skill-repo/skills/obsidian-vault-kb/SKILL.md

name, description

name

description

obsidian-vault-kb

Reads an Obsidian vault as a knowledge base and uses its notes (Markdown files, frontmatter, tags, wikilinks, folder structure) to answer questions and help solve problems, regardless of the vault's subject matter. Always use this skill when the user refers to their "vault", "notes", "docs", "wiki", "Obsidian", or a personal/topic-specific knowledge base — even if "Obsidian" isn't mentioned explicitly, as long as the context suggests a personal note collection as the information source (e.g. "check my notes", "what did I write about this", "according to my docs"). Covers both plain lookup and creating/updating notes, depending on the mode configured on first contact.

Obsidian Vault as Knowledge Base

This skill makes an Obsidian vault (a directory of Markdown files with Obsidian-typical structure: YAML frontmatter, [[wikilinks]], #tags, folder conventions) usable as a searchable knowledge base, regardless of what topic the vault covers (e.g. technical documentation, project notes, research or study notes).

Workflow

1. Check configuration (always first)

Configuration lives in ~/.agent-skills/obsidian-vault-kb/config.json. Before any substantive action, check whether this file exists:

cat ~/.agent-skills/obsidian-vault-kb/config.json 2>/dev/null

If the file exists: Use the configuration from it (vault path(s), mode) and go straight to step 2 (search). Do not ask again.

If the file is missing (first call): Briefly ask the user:

1. Path to the vault (absolute path, e.g. /home/user/vaults/notes). Multiple vaults are possible — assign a short name to each.
2. Mode:
   • read-only — read only, no write access whatsoever
   • append — read + append new findings as a new, dated note (existing notes are never modified)
   • maintain — read + actively update/extend existing notes (e.g. status fields, ongoing logs)

Then create the configuration file:

mkdir -p ~/.agent-skills/obsidian-vault-kb
cat > ~/.agent-skills/obsidian-vault-kb/config.json << 'EOF'
{
  "vaults": [
    {"name": "notes", "path": "/absolute/path/to/vault"}
  ],
  "mode": "append"
}
EOF

Briefly confirm what was saved, then proceed. The user can change the configuration at any time by explicitly saying so (e.g. "use a different vault from now on", "switch to read-only mode") — then overwrite the file with the new values.

2. Search the vault

For questions/problems, first use the folder structure as a topical categorization, then dig into content. Details and example commands are in references/search-strategy.md — consult it for any non-trivial search, especially when using tags/frontmatter/wikilinks.

Short version of the approach:

1. Get an overview of the vault structure: <skill-dir>/scripts/vault_index.sh [vault-name] — returns folders as rough categories, note counts, existing frontmatter tags, and possible index/MOC files.
2. Targeted full-text search with <skill-dir>/scripts/vault_search.sh "<query>" [vault-name] [subfolder] — scoped to the most plausible subfolder from step 1 where useful.
3. For a specific note, follow backlinks with <skill-dir>/scripts/vault_backlinks.sh "<note-name>" [vault-name] to find related notes that link to it.
4. Open matching files (via the view/read tool, not a shell command) to read their frontmatter (tags, status, aliases) and content in full once a promising candidate has been found.

These three scripts always resolve the vault path from ~/.agent-skills/obsidian-vault-kb/config.json themselves and refuse to operate outside the configured vault — they never take a raw filesystem path as an argument. This is intentional: it's what allows them (and only them) to be safely whitelisted in Claude Code's permissions without granting broader shell/filesystem access. See "Setup and permissions" below and references/search-strategy.md for manual fallback commands (find, rg, grep) for cases the scripts don't cover — those are not whitelisted and will prompt for confirmation, by design.

Always start with a narrow, targeted search and only widen it if needed — don't read the whole vault unstructured.

3. Formulate the answer

• Base answers explicitly on the notes found, briefly citing the source (file name/note title); don't invent anything the vault doesn't support.
• If the vault doesn't contain relevant information, say so openly instead of guessing, and clearly separate that from general domain knowledge if used.
• For topics with exact detail values (e.g. configuration data, numbers, names, version info), carry these over verbatim from the notes instead of paraphrasing, since accuracy matters here.

4. Write notes (only in append or maintain mode)

• append: File the new finding/solution as a new file, e.g. <vault>/Notes/YYYY-MM-DD-<short-topic>.md with frontmatter (tags, date, possibly related) and wikilinks to affected topics/systems. Never modify existing files.
• maintain: Extend an existing relevant note directly (e.g. append a new "Update YYYY-MM-DD" section or update a status field in the frontmatter) instead of creating a new file, when an existing note is the right place for the content.
• read-only: Never create or modify files in the vault. If the user asks anyway, briefly point out the current mode and ask whether the configuration should be changed.
• Before writing, always briefly summarize what will be written; for more substantial changes (maintain mode), explicitly confirm before modifying an existing note.

Setup and permissions

This SKILL.md and the scripts//references/ next to it are the tool-neutral core of this skill (per the open Agent Skills spec at agentskills.io) and don't assume any particular host tool. Configuration always lives at the tool-neutral path ~/.agent-skills/obsidian-vault-kb/config.json, regardless of which agent is running this skill.

Host-specific setup helpers live under vendor/<tool>/ in this repo, not here. For Claude Code specifically, vendor/claude-code/plugins/obsidian-vault-kb/ provides a commands/setup.md slash command — automatically namespaced by Claude Code's plugin system and invoked as /obsidian-vault-kb:setup — plus a permissions-whitelist.template.json for Claude Code's Bash permission system. Only three exact, absolute-path commands are whitelisted there — the three wrapper scripts in scripts/ — never a generic Bash(find:*), Bash(rg:*), Bash(grep:*), or Bash(cat:*). Those would allow reading anywhere on the filesystem; the wrapper scripts instead resolve the vault path only from ~/.agent-skills/obsidian-vault-kb/config.json and refuse to operate outside it, so whitelisting them by exact path doesn't widen access beyond the configured vault.

If no host-specific setup helper exists for the tool currently running this skill, or configuration is simply missing, run through the first-call flow in step 1 above directly instead.

Nothing that writes into the vault or into the config file is whitelisted — those keep prompting for confirmation every time, in append/maintain mode, by design.

Notes

• This skill doesn't replace the user's own folder-structure conventions — the structure detected in step 1 determines how content is categorized, not a fixed predefined schema.
• Don't automatically read binary files/attachments (.pdf, images) in the vault, just reference them, unless the user explicitly asks for it.
• Ignore the vault's .obsidian/ configuration directory, it contains no knowledge content.