elegy-obsidian

Files (4)

• README.md
• SKILL.md
• readiness.json
• obsidian-cli-catalog.md · references/

SKILL.md (first lines)

> **Invocation posture**: user-invoked only. This skill wraps the Obsidian CLI and can mutate vault content (create, append, patch, move, delete, task toggle). It must not be auto-invoked by the model.
>
> **Readiness: concept; not agent-routable.** The required Obsidian runtime and an installed non-fixture vault task have not been verified.

# Elegy Obsidian

## Purpose

`elegy-obsidian` is a convenience layer over the official `obsidian` CLI
shipped with Obsidian Desktop 1.12.7+. It is a foundation surface only;
it deliberately does **not** mirror, attach, resolve, or list Obsidian
vault state into the Elegy planning authority. That work belongs to a
future `elegy-planning obsidian ...` Rust subcommand set.

Obsidian is treated as a **non-authoritative** mirror:

- The official `obsidian` CLI is a black-box process boundary; the
  skill does not parse or normalize its output into an Elegy
  planning schema.
- Durable cross-session state continues to live in `elegy-planning`
  (goals, roadmaps, plans, todos, issues, review points) backed by
  SQLite.
- Vault reads, file appends, and search results must not be written
  into paths that would shadow planning authority (for example,
  `.elegy/backlogs/`, `roadmaps/`, or any spec/ADR location owned
  by another skill).

## Prerequisite

The official `obsidian` binary must be available. It is shipped with
Obsidian Desktop 1.12.7+; the CLI is not enabled by default. The
Obsidian Desktop app must also be running for the CLI to function —
commands fail if the app is not open.

If the `obsidian` CLI is not installed or not reachable, this skill
cannot function — inform the user and offer to install Obsidian
Desktop or enable the CLI in Obsidian Settings -> General ->
"Command line interface".

## Binary Resolution

The `obsidian` binary must be reachable from the current shell. Use
this resolution order:

1. **Check PATH**: run `obsidian version`. If it resolves, use `obsidian`
   directly for all commands.
2. **WSL / non-PATH fallback**: on Windows Subsystem for Linux, the
   `obsidian` app-execution alias is on the Windows PATH but not the
   WSL PATH. Resolve via:
   ```bash
   cmd.exe /c "where obsidian"
   ```
   This returns the full Windows path.
   Convert to a WSL path and use it for all subsequent invocations.
3. **Known install root**: if `where` fails, check the default
   Obsidian Desktop install location (typically under the user's
   local AppData Programs directory).

Once resolved, use the full binary path for every `obsidian` call in
the session. Do not re-resolve unless the first attempt fails.

If none of the above resolve, the CLI is not installed or not enabled.
Guide the user to install Obsidian Desktop 1.12.7+ and enable the CLI
under Settings -> General -> Command line interface.

## Vault Context

Before invoking any vault command, load the vault context:

1. **Read config**: `~/.elegy/obsidian-vault.json` contains
   `vaultPath` (the vault root). Derive the vault name from the
   folder basename (e.g., a vault at `~/Documents/Dev` → vault
   name `Dev`).
2. **Fallback**: if config is absent, run `obsidian vault list` to
   discover registered vaults. Use the first (or prompt the user
   to choose if multiple).
3. **Pin vault name**: pass `vault=<name>` on every subsequent
   `obsidian` call. The active-vault default is platform-specific
   and unreliable when multiple vaults are registered.

### Vault layout conventions

Obsidian vaults use theme-based subdirectories. The standard layout
(for a vault named `Dev`):

```text
Dev/
  Projects/       ← project notes (theme: Projects)
  Research/       ← research notes (theme: Research)
  Tasks/          ← task lists (theme: Tasks)
  Resources/      ← resource/link collections (theme: Resources)
  Index.md        ← navigation hub (links to all sections)
```

Frontmatter conventions (per the vault-notes spec):

```yaml
---
id: my-note-slug        # derived from filename (My-Note.md → my-note)
title: My Note          # human-readable title
theme: Projects         # derived from parent directory name
tags: [tag1, tag2]      # YAML array
created: ISO-timestamp
updated: ISO-timestamp
archived: false
---
```

These are conventions, not enforced. The `theme` field corresponds to
the parent directory name. `Index.md` at the vault root is the
navigation hub — read it first to orient within the vault.

## Orient-Once Protocol

At the start of each session (or when the user asks to interact with
the vault), run this 3-command bootstrap:

1. `obsidian version` — confirm CLI is reachable, note version.
2. `obsidian vault list` — confirm vault name and path (or read from

From Sofreshx/Elegy, Apache-2.0.

More from Sofreshx/Elegy