Claude Code Skills for Obsidian Vaults

January 11, 2025·Ecosystem Insights, Development Practices·Agent Skills, Claude Code, Obsidian, Knowledge Management

Obsidian vaults often evolve into the “source of truth” for personal or team knowledge: notes, project logs, meeting minutes, diagrams, tasks, and lightweight databases. Claude Code can help maintain that vault—but only if it understands the vault’s conventions and file formats.

This article shows a practical way to “teach” Claude Code how to work inside an Obsidian vault by packaging a vault-focused Skills bundle: clear rules for enhanced Markdown, structured data views (Bases-style), and Canvas files.

Why a Vault-Focused Skills Bundle?

Obsidian commonly uses conventions that are valid in Obsidian, but easy for generic Markdown tooling to break:

Wikilinks: [[Note Name]], [[Note#Heading]]
Embeds: ![[image.png]]
Callouts: > [!note], > [!warning]
Frontmatter: YAML metadata blocks
Canvas: .canvas JSON documents for visual thinking

If Claude edits without these rules, you risk “almost correct” changes: broken links, malformed frontmatter, and drifting schemas. A small Skills bundle prevents that by making invariants explicit.

Three Skills to Cover a Vault

Split the vault rules by file type. Keep each skill narrow, opinionated, and testable.

1) `obsidian-markdown`: Enhanced Markdown

Owns: *.md in the vault.

Must preserve:

Wikilinks and embeds ([[...]], ![[...]])
Frontmatter keys and value types
Callout formatting and indentation

Example guidance to include:

Rules:
- Do not convert [[wikilinks]] to normal Markdown links unless explicitly asked.
- When editing frontmatter, keep existing keys; only add new keys when requested.
- Keep callouts in the same style (e.g. > [!note]) and preserve indentation.

2) `obsidian-bases`: Structured Data Views (Bases-style)

Owns: your “base” definition files (whatever convention you use) and the property conventions across notes.

Goal: make queries reproducible by editing a single “view definition” instead of ad-hoc search.

Example Base File (YAML):

filters:
  and:
    - 'status == "in-progress"'
    - 'priority > 3'

views:
  - type: table
    name: "High Priority Tasks"
    order:
      - file.name
      - priority

3) `json-canvas`: Canvas Files

Owns: *.canvas.

Must preserve:

Stable node IDs
Valid edge references
Required node fields

Canvas Example (JSON):

{
  "nodes": [
    { "id": "n1", "type": "text", "x": 0, "y": 0, "width": 320, "height": 180, "text": "Core idea" }
  ],
  "edges": []
}

Recommended Bundle Layout

Put the bundle inside the vault so it travels with the repo and is reviewable like code:

your-vault/
  .claude/
    skills/
      obsidian-vault/
        obsidian-markdown/
          SKILL.md
        obsidian-bases/
          SKILL.md
        json-canvas/
          SKILL.md

A lightweight SKILL.md frontmatter pattern:

---
name: "obsidian-markdown"
description: "Use when reading or editing vault Markdown with wikilinks, callouts, embeds, and YAML frontmatter."
triggers: ["[[", "wikilink", "callout", "frontmatter", ".md"]
---

Practical Workflows

Workflow 1: Refactor Notes Without Breaking Links

Ask Claude Code to rename a concept across notes, update headings, and keep backlinks stable. The Markdown skill is where you specify “never rewrite wikilinks unless told”.

Workflow 2: Turn Notes Into a Lightweight “Database”

Define a set of property conventions (status, priority, due_date, …) and let Claude adjust your view definitions in a controlled way.

Workflow 3: Maintain Diagrams in Canvas

If you keep architecture maps in .canvas, a dedicated skill prevents schema drift (missing fields, duplicated IDs, invalid edges).