Initial commit

skills/obsidian-vault-kb/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: obsidian-vault-kb
+description: 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:
+
+```bash
+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:
+
+```bash
+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.