Obsidian CLI Plugins

Obsidian CLI Plugins

Human readers can use SKILL.zh-CN.md and matching *.zh-CN.md references. Agent runtimes must load this English SKILL.md and the English references only. Update each English/Chinese document pair in the same change; the bilingual documentation test enforces the required counterparts.

Operating Model

Use the bundled Python scripts as the stable interface. All executable code and launchers must live under scripts/; do not add root-level compatibility scripts. When a workflow needs repeatable parsing, Git coordination, attachment handling, or note edits, extend scripts/obsidian_cli_plugins/ instead of writing ad hoc shell snippets.

Run doctor first on a new host, container, SSH session, OpenClaw runtime, or unfamiliar Agent runtime. Return and consume JSON for cross-agent handoff, and stop on ok=false, reason, nonzero return codes, unmerged, or merge_head.

Plugin Relationship

This skill is the required component for Obsidian functionality. It owns vault discovery, Git preflight, record creation, attachment copying, staged-attachment consumption, and sync.

The obsidian-media-claim OpenClaw plugin is optional. It does not replace this skill and cannot create Obsidian records by itself. Load references/openclaw.md only for OpenClaw sync, staged media, phone-channel media, or media-only-then-later-text workflows.

Scope Boundaries

After this skill is selected, confirm the request is operating on a real Obsidian vault, especially a configured vault such as obsidian-2026.

Use this skill for vault status, Git sync/status inside a vault, journal records, Tasks todos, project files under 01_project/, plugin/native commands, safe vault reads/searches, and OpenClaw skill sync.

Do not use this skill for generic project management, generic Markdown editing, unrelated Git operations, database/business records, or screen/audio/video recording unless the result is explicitly going into an Obsidian vault. Use obsidian-vault-maintainer only for OpenClaw memory-wiki compatibility, especially requests that explicitly mention memory-wiki render mode or openclaw wiki obsidian ....

Quick Start

Run doctor first on unfamiliar runtimes. For common requests, load references/fast-paths.md and use its route table instead of loading larger references.

python3 <skill-dir>/scripts/obsidian_workflows.py doctor

Configure per host or agent with environment variables instead of editing scripts:

export OBSIDIAN_VAULT=<vault-name>
export OBSIDIAN_VAULT_PATH=<absolute-vault-path>
export OBSIDIAN_BIN=obsidian

Use --vault current or --vault auto to target the single currently open vault from Obsidian config. Use --vault-path for one-off calls when environment variables are unavailable.

Reference Routing

Treat SKILL.md as the router. Load only the smallest reference needed for the user's requested function.

• references/fast-paths.md: first stop for common requests and high-frequency commands.
• references/runtime-sync.md: runtime config, Git sync, plugin command IDs, security gates, portability, and cross-agent handoff.
• references/reminders.md: Tasks Datetime reminder prerequisites, plugin and Agent configuration, scheduling, testing, and diagnosis.
• references/vault-safety.md: safe read/search/summarization of arbitrary vault content or files outside 20_plan/.
• references/task-query.md: 今日新增待办, full today todo reports, and weekly todo reports.
• references/task-add.md: adding tasks, date/tag inference, journal creation, and placement rules.
• references/record-workflows.md: inline records, file-mode records, local attachments, and record success criteria.
• references/record-body.md: file-mode record body sections, formatter behavior, and unified LLM analysis fields.
• references/project-records.md: project files under 01_project/, template_structure, target_id, semantic project JSON, and Linter behavior.
• references/openclaw.md: OpenClaw install/sync, staged media, phone-client media input, and media-only messages followed by later text records.
• references/official-cli.md: native Obsidian CLI command lookup beyond installed community plugin command IDs.
• references/extensions.md: adding workflow support for newly installed Obsidian plugins.
• references/field-guide.md: onboarding a new Agent, reviewing vault layout, write targets, template dependencies, or updating the skill from real-session lessons.
• references/tasks.md and references/workflows.md: compatibility indexes only; prefer the specific files above.

Execution Rules

• On multi-vault hosts, inspect doctor.configured_vaults and doctor.resolved_vault; use --vault current only when the single-open-vault result is clear.
• Use safe-read or safe-search before returning vault content. Otherwise apply references/vault-safety.md and redact sensitive content.
• Use add-task-sync for task additions and record-sync for record additions unless the user explicitly asks for local-only writes.
• For task additions, generate the required TaskAnalysis JSON in the current Agent reasoning and invoke the write command once with --analysis-json and a stable --request-id. Do not use analyze-task --prompt-only as a normal OpenClaw workflow; it cannot reliably trigger a nested LLM pass.
• For 记录 <content> with no explicit period/date, write an inline record to today's daily journal 记录 section with the original text unchanged. Load references/record-workflows.md before changing record behavior.
• Use file-mode records only for separate cards/notes, analysis, long-term capture, knowledge processing, or any attachment/media workflow. Load references/record-body.md; for staged or cross-agent media, also load references/openclaw.md.
• For media files uploaded in earlier channel messages, load references/openclaw.md before consuming staged attachments. Do not use attachment-list --batch-key default, stale staged ids from model memory, or direct cache directory reads.
• For file-mode records, generate semantic JSON in the current Agent reasoning and pass it directly as --analysis-json; do not use analyze-record --prompt-only as a nested-LLM workflow. analyze-record is debug/schema inspection only.
• For project notes under 01_project/, load references/project-records.md, inspect project-template-structure when routing is needed, then generate the required target_id JSON in the current Agent reasoning before writing. Do not use analyze-project-record --prompt-only as a nested-LLM workflow.
• If a supplied attachment has no readable local path, stop with record-attachment-required, attachment-path-unavailable, or unsupported-channel-attachment-record instead of writing a partial record.
• Before pull, push, commit-sync, or note edits, run git-status; stop on conflict state. Prefer add-task-sync, record-sync, or git_preflight_clean so host git clean/pull/push/commit sequencing is enforced. Fall back to Obsidian Git plugin commands only when the host git executable is not found, not when host Git returns a conflict, auth, pull, push, or commit error.
• Treat Executed: <command-id> as dispatch success only; verify the actual vault/file/plugin effect afterward.
• When a configuration value, Vault target, delivery recipient, template choice, write location, or other material fact is uncertain, stop and ask the user to decide. Do not guess, infer a preference, or make an irreversible choice on the user's behalf.
• Ask before destructive operations such as discard, delete, reset, uninstall, vault-wide cleanup, or permanent deletion.
• For "今日新增待办", "今天新增任务", or equivalents, prefer tasks show --period day --date today; do not run broad vault searches unless the user asks for them.
• For Tasks Datetime notifications, load references/reminders.md. This feature requires Tasks Datetime to publish a plan from tasks with complete non-midnight date-times; date-only tasks cannot trigger an Agent reminder.
• Never create backup files or directories inside this skill. Use ~/.codex/skill-backups/obsidian-cli-plugins/ or OBSIDIAN_SKILL_BACKUP_DIR for external archives.

For OpenClaw, sync into the current managed skills directory, typically ~/.openclaw/skills/obsidian-cli-plugins, with:

python3 ~/.codex/skills/obsidian-cli-plugins/scripts/sync_openclaw.py