How to use the Obsidian CLI read transport agent skill

What is an agent skill and what does wiki-cli do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a task matches the skill's description. The wiki-cli skill covers read-only access to an Obsidian vault.

The skill first checks whether Obsidian's official command-line tool, the obsidian executable, is actually usable. Having the binary installed is not enough: the Obsidian app must be running and command line access must be enabled. If the tool is ready, the agent can use it to read notes, search, and look up backlinks, tags, or Bases results. If it is not ready, the agent reads the files in the vault directly and uses rg (ripgrep) for search.

• Reads a note by path using the CLI when it is ready
• Searches the vault with the CLI or with rg as a fallback
• Falls back to reading files directly when the CLI is not usable
• Never creates, edits, moves or deletes notes through the command line

How do you install the wiki-cli skill?

Download the ZIP for skills/wiki-cli from this page and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

The skill refers to scripts and reference files inside the installed claude-obsidian product folder, so that product must be installed at a fixed absolute location. The skill expects scripts/detect-transport.sh to exist there.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload

What do you need before the skill works?

The skill needs the claude-obsidian product folder installed, with scripts/detect-transport.sh inside it. It also needs bash and rg (ripgrep) for detection and search.

The CLI path has extra requirements. The Obsidian desktop app must be running with command line access enabled, and the official obsidian executable must be on your PATH. The executable is optional: without it, the filesystem fallback still works.

• Obsidian desktop app, running, with command line access enabled (CLI path only)
• Official obsidian executable on the PATH (optional)
• bash and rg (ripgrep)
• Installed claude-obsidian product folder containing scripts/detect-transport.sh

How does the agent check which transport to use?

The skill tells the agent to probe the transport without saving anything. The detector reports whether the CLI is usable, and the agent should trust the usable flag rather than only whether the binary is present or the exit status.

If you want a saved snapshot, the detector can write .vault-meta/transport.json. Use this only when you or your setup workflow asks for it. The file is runtime configuration, not note content, and a valid manual_override recorded by the detector is preserved.

• Quick probe, nothing saved: the --peek option with --vault
• Refreshed snapshot written to .vault-meta/transport.json: the --force option with --vault

How do you trigger the skill with natural requests?

You do not need to type commands. Ask in plain language and mention the vault or the kind of lookup you want. The skill's description includes terms such as Obsidian search, Obsidian read, backlinks, tags, Obsidian command line, and which transport.

Be specific about what you want read or found. Naming a note path or a search phrase helps the agent pick the right read.

• "Use wiki-cli to find every note that mentions project budgets in my vault."
• "Check which transport Obsidian is using for my vault."
• "Show me the backlinks for the note Meeting notes/2024 planning."
• "Read the note Reading list in my Obsidian vault."

What safety limits apply?

The skill runs scripts, so review them before installing. Its own instructions say it does not use the network. Read-only use is enforced by its instructions: the agent must not run CLI create, write, append, property-set, daily-append, move, rename or delete commands, and must not replace them with direct filesystem writes.

The skill also tells the agent to reject absolute note arguments, path traversal, symlinks, and resolved paths outside the selected vault. Any change to your notes must go through a separate reviewed transaction via the claude-obsidian transaction core, which is not part of these files.

• Runs scripts: yes. Read the detector script before use.
• Uses network: no, according to the skill's description.
• No CLI writes. Changes go through the separate transaction core.
• Paths must stay inside the selected vault.

What tips help the skill work well?

Keep the Obsidian desktop app open if you want the CLI path. If the agent reports that the CLI is not ready, check that the app is running and that command line access is enabled, then try again. Otherwise the agent will read the files directly, which is slower for big vaults but works without Obsidian.

Use the claude-obsidian product path consistently. The skill resolves references from its own location under the product root, not from your vault, so moving the skill folder can break its links.

• Start Obsidian before asking for CLI-based reads
• Expect filesystem fallback when the CLI is not ready
• Keep the claude-obsidian folder in one fixed location