# Obsidian

> Operates the user's Obsidian vault as a durable knowledge surface. Resolves the active vault, gates writes on its contract, creates and maintains knowledge notes, Bases, links, and clippings intended for knowledge, and recalls what earlier sessions said. Use for work inside the vault or questions about what it contains. Do not use for Sjel-owned records, generic Markdown outside the vault, prose style, or authoring skills.

- Skill: `larsboes/obsidian-2` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add larsboes/obsidian-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/larsboes/obsidian-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: larsboes (https://skillmd.com/u/larsboes)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/larsboes/obsidian-2

---


# Obsidian

The active vault holds durable knowledge. Sjel owns operational records and unsorted source
material. Keep one canonical home for each record and link to its owner instead of copying it.

## Resolve and gate

Always resolve the configured vault and read its contract, if one is configured, before changing
vault contents. The contract path is set per machine with `contract_path` in the overlay's
`config/knowledge.toml`; the contract is optional. When one is configured, it owns placement, the
no-doubling law, naming, and frontmatter typing. When none is configured, follow the vault's
existing conventions: read neighbouring notes, their folders and frontmatter before writing.

**Local vault mode.** When the overlay's `config/knowledge.toml` sets `local_files = true`, the
user selected direct file access for the vault at `vault_root`, and only for that vault. Read,
search, create and edit its files with the local file tools (`read`, `grep`, `find`, `edit`,
`write`), in Pi and in other harnesses. Before the first change in a session, read the contract
that `scripts/vault contract` names. Use `obsidian_*` tools only for Obsidian-aware operations,
such as the active note, backlinks, or a heading-targeted patch. Local access does not pass the
Obsidian access policy: it records no clearance, restricts no egress tools, writes no audit line
and has no version check against a concurrent edit in Obsidian. Use it only for a vault with no
confidential notes. The vault contract still governs every write, including read-only folders.

Without local vault mode, in Pi, use the governed `obsidian_*` tools by default. Call `obsidian_contract` before the first
mutation in a session. It loads the configured contract from the vault through Obsidian and gates
writes against its current digest, or reports that no contract is configured for this machine. If a
contract is configured but missing, stop and say so — do not improvise structure or substitute an
overlay-local contract.

If the Obsidian access tools are unavailable, a user may provide an exact absolute path to a local
vault note and ask for it to be read. Before using the filesystem read tool, establish that the
active model is allowed to read that exact note under the vault's C0–C3, `agent_access`, and path
rules. Permit this fallback only for C0 notes whose effective agent access is standard, when the
full access decision is known and the session has no stricter clearance or egress requirement; stop
if the classification or policy cannot be checked. C1, C2, C3, restricted, or unclassified notes
must not enter context through this fallback. Read only the named file; do not search the vault, follow links,
or read adjacent notes. This fallback is read-only and cannot bypass a refusal from an available
governed tool. State that the note was read outside the vault access policy.

Outside Pi, resolve the vault and contract through the bundled helper:

```bash
scripts/vault root
scripts/vault contract
```

`scripts/vault contract` prints the configured contract's path, or reports on stderr that none is
configured. If it fails, stop and report it; do not invent a replacement structure. Follow the
contract's note types, metadata, placement and link rules.

In Pi, use the narrowest governed operation that fits: `obsidian_read` supports whole-note, heading,
block, and frontmatter targets; `obsidian_outline`, `obsidian_search`, `obsidian_backlinks`,
`obsidian_properties`, and `obsidian_tags` cover low-token discovery. Read `.base` files with
`obsidian_base_read`; validate drafts with `obsidian_note_validate` or `obsidian_base_validate`
before writing. Create with `obsidian_create`, extend with `obsidian_append`, and make structural
edits with `obsidian_patch`. Reserve `obsidian_write` for deliberate whole-note replacement.
Moves and deletes require confirmation. Outside local vault mode, never work around a
mutation refusal by switching to shell or direct filesystem access.

## Read before writing

Search for an existing owner and read it before answering a question or adding material. Type new
notes at birth with the required properties. Update the owner in place, link related concepts, and
avoid duplicate claims. Use the existing `Knowledge/` domains, MOCs and `Knowledge.base` views.
Create no capability data, operational inbox, or second copy of a Sjel record in this vault.

## References

| Task | Read |
|---|---|
| Wikilinks, embeds, callouts, properties | `references/markdown.md` |
| `.base` views, filters, formulas | `references/bases.md`, then `obsidian_base_validate` |
| `.canvas` files | `references/canvas.md` |
| Obsidian CLI | `references/cli.md`, then `obsidian help` |
| Ingest, synthesize, or lint knowledge | `references/wiki.md` |

## Knowledge capture

Capture a web source into Sjel first when it is an unsorted source or operational record. Add a
vault note only when the result is durable knowledge or a source note allowed by the vault
contract. Preserve provenance and link the knowledge note to its Sjel-owned source where useful.
Do not treat the vault as a general clipping inbox.

## Verification

After edits, check frontmatter, links, and the contract's lint requirements. Bases and canvases
require visual verification in Obsidian; report when that check remains outstanding. Never place
secrets in notes.

