skill-repo/vendor/claude-code/plugins/obsidian-vault-kb/commands/setup.md

---

description: Set up the obsidian-vault-kb skill (vault path, mode, minimal permissions whitelist) argument-hint: [vault-path] [mode]

Set up the obsidian-vault-kb skill end to end. As part of the obsidian-vault-kb plugin, this command is automatically namespaced by Claude Code and invoked as /obsidian-vault-kb:setup — no manual filename prefixing needed. Follow these steps in order.

1. Determine the skill's install directory

This plugin's skills/obsidian-vault-kb/ is a symlink into the repo's tool-neutral skills/obsidian-vault-kb/ directory (the single source of truth for SKILL.md, scripts/, and references/, shared across all vendor adapters in this repo). Resolve it to its real, absolute, symlink-free path:

realpath <plugin-dir>/skills/obsidian-vault-kb

This resolved path is <SKILL_DIR> for the rest of this setup — you'll need it exactly for step 4. Use the real path (not the symlink path) so the permissions whitelisted in step 4 keep working even if this plugin directory is relocated relative to the shared skills/ directory.

2. Gather vault path and mode

If $ARGUMENTS contains a vault path and/or mode, use those directly. Otherwise ask the user:

1. Absolute path to the Obsidian vault (if there's more than one vault, ask for a short name per vault too).
2. Mode: read-only, append, or maintain (as defined in SKILL.md — explain briefly if the user is unsure which to pick).

Validate the path exists and is a directory before continuing:

test -d "<vault-path>" && echo OK || echo "MISSING"

If missing, ask the user to correct it before proceeding.

3. Write the skill configuration

The config path is tool-neutral (not Claude-specific), so this same file would be reused if another Agent-Skills-compatible tool ran this skill:

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

Confirm the written content with the user.

4. Generate and merge the minimal permissions whitelist

Read permissions-whitelist.template.json (next to this plugin's plugin.json, i.e. <plugin-dir>/permissions-whitelist.template.json). It whitelists exactly three commands, each pinned to its full absolute path — no generic Bash(find:*), Bash(rg:*), Bash(cat:*), etc., since those would allow reading anywhere on the filesystem rather than just the vault:

• Bash(<SKILL_DIR>/scripts/vault_index.sh:*)
• Bash(<SKILL_DIR>/scripts/vault_search.sh:*)
• Bash(<SKILL_DIR>/scripts/vault_backlinks.sh:*)
• Read(~/.agent-skills/obsidian-vault-kb/config.json)

These three scripts resolve the vault path only from ~/.agent-skills/obsidian-vault-kb/config.json and refuse to operate on any path outside it (see their source), so whitelisting them by exact path does not grant broader filesystem access — not even to other files in the same scripts/ directory, since the wildcard is per-script-file, not per-folder.

Steps:

1. Replace every <SKILL_DIR> placeholder in the template with the real, symlink-resolved absolute path from step 1.
2. Locate the target settings file: prefer the project-level .claude/settings.json if a project is open, otherwise the user-level ~/.claude/settings.json. Ask the user which one they want if unclear.
3. If the target file doesn't exist yet, create it containing just the substituted permissions.allow array.
4. If it exists, read it first and merge: add only entries from the substituted array that aren't already present in the target file's permissions.allow array. Don't duplicate entries, don't remove or overwrite unrelated existing permissions in the file.
5. Show the user exactly what was added (the four entries above with the real path filled in) before writing, so they can see precisely what they're approving.

Do not add anything beyond these four entries. In particular, do not whitelist writing to the vault or to the config file — those keep prompting for confirmation every time, by design, in append/maintain mode.

5. Make the helper scripts executable

chmod +x <SKILL_DIR>/scripts/vault_index.sh <SKILL_DIR>/scripts/vault_search.sh <SKILL_DIR>/scripts/vault_backlinks.sh

Note this modifies the shared skills/obsidian-vault-kb/scripts/ files in the repo (via the resolved real path), not a plugin-local copy — that's expected, since the symlink means there is only one copy on disk.

6. Confirm and offer a test run

Summarize to the user:

• Vault path(s) and mode that were configured
• The exact four permission entries that were added, and where (project vs. user settings)
• That nothing else was whitelisted — every other command, and any write into the vault, still prompts for confirmation

Then offer to run <SKILL_DIR>/scripts/vault_index.sh as a quick sanity check, if the user wants to see it working right away.