Obsidian Vault Integration

Read and write data with an Obsidian vault used as a shared knowledge base. Use when an agent needs to read vault notes (business plan, tasks, milestones, te...

Security Scan

This skill is internally coherent: it reads and writes local Obsidian markdown files under a provided vault path and does not attempt unexpected network access or require unrelated credentials, but there are a few minor configuration/clarity notes you should review before installing.

Purpose & Capability

Name/description match the included scripts (vault-read.py, vault-write.py) which read and modify markdown files in a local Obsidian vault. Minor mismatch: SKILL.md documents and uses OBSIDIAN_VAULT_PATH (and references a default in AGENTS.md) and the scripts reference AGENT_NAME for audit logging, yet the registry metadata lists no required env vars and AGENT_NAME is not declared—this is a small documentation/configuration inconsistency but not evidence of malicious intent.

Instruction Scope

Runtime instructions and scripts operate purely on local files under the vault path: discovery (vault.rglob('*.md')), parsing frontmatter, extracting tasks/team sections, and safe writes with conflict detection and an audit log in <vault>/.vault-audit.log. There is no network I/O, no attempts to read unrelated system configuration, and no exfiltration endpoints. Note: because the vault path is supplied (or taken from a default), if that path is misconfigured to a sensitive location the scripts will operate on whatever markdown files exist there.

Install Mechanism

No install spec — instruction-only with bundled scripts. Nothing is downloaded or written to system locations by an installer. The scripts rely on standard Python and an optional 'frontmatter' package if installed.

Credentials

The skill does not request credentials or secrets. It uses OBSIDIAN_VAULT_PATH (documented in SKILL.md but not listed as a required env var in registry metadata) and reads AGENT_NAME for audit entries if present; neither variable is sensitive by design. Ensure the vault path is restricted to the intended vault; otherwise the skill can read/write any markdown under that path.

Persistence & Privilege

always:false and model invocation is allowed (default) — normal for a user-invocable skill. The skill does not request permanent system-wide presence or modify other skills/configurations. Writes are constrained to files under the given vault and to a local audit log file inside the vault.

Assessment

This skill appears to do what it says: read and update markdown files in a local Obsidian vault. Before installing, check these points: (1) Confirm what default path your agent would use (AGENTS.md) so the skill won't be pointed at a sensitive directory by accident; explicitly set OBSIDIAN_VAULT_PATH to the correct vault. (2) If you run multiple agents and want access control, note SKILL.md's 'Solo mode' is the default — there is no enforced per-agent permissioning yet. (3) AGENT_NAME is used for audit logging but isn't declared in metadata; if you rely on accurate agent attribution, set AGENT_NAME in the environment. (4) No network calls or secrets are requested by the code, but review and test the scripts in a sandboxed vault if you want to be extra cautious. If you need stronger guarantees (e.g., prevent accidental access to non‑vault files), consider running the scripts under a restricted account or container whose filesystem is limited to the intended vault path.

Integrates OpenClaw agents with an Obsidian vault for shared knowledge management. Supports structured reading of task lists, milestones, team info, and safe writes back to vault files.

Configuration

Set the vault path via environment variable OBSIDIAN_VAULT_PATH. If not set, uses the default path noted in AGENTS.md.

Environment variables used:

• OBSIDIAN_VAULT_PATH — Path to the Obsidian vault directory (optional, defaults to agent's configured path)

Quick Start

Read tasks from vault

python scripts/vault-read.py <vault-path> --file open-questions.md --format json

Returns JSON array of tasks parsed from checkbox items, with priority (critical/important/nice), status (todo/done), owner, and title.

Add a task to the vault

python scripts/vault-write.py <vault-path> --file open-questions.md --action add-task --title "New task" --priority important --owner Dave

Mark a task done

python scripts/vault-write.py <vault-path> --file open-questions.md --action mark-done --task-id 3

File Discovery

Files are discovered by their frontmatter type: field as the primary method. If a file is moved to a subfolder, it's still found by metadata.

---
type: open-questions
status: active
---

Fallback chain:

1. Frontmatter type: field (most reliable — survives moves)
2. Filename pattern matching (e.g., *open-questions*)
3. Full-text search (slowest, last resort)

See references/file-formats.md for parsing rules per file type.

Error Handling

Code	Meaning	Recovery
ERR_VAULT_NOT_FOUND	Vault path doesn't exist	Check OBSIDIAN_VAULT_PATH or AGENTS.md
ERR_FILE_NOT_FOUND	Requested file not found	Run discovery to find by metadata
ERR_PARSE_FAILED	Malformed markdown	Return partial data with warning
ERR_CONFLICT	File changed since last read	Re-read, resolve manually

Safety

• All writes are logged to <vault>/.vault-audit.log (timestamp, agent, file, action)
• Timestamp check prevents overwrites when file has changed
• Solo mode (default): all agents can read/write everything
• Team mode (v2): per-agent folder permissions

Permissions

Solo mode (default): No config needed. All agents have full read/write access.

Team mode (v2, not yet implemented): Optional permissions block in SKILL.md for folder-level access control per agent.

Scripts

• vault-read.py — Read and parse vault files into structured JSON
• vault-write.py — Write updates back to vault files with safety checks

References

• references/file-formats.md — Parsing rules for each file type