DEV Community

Cover image for Open Source Project of the Day (#112): obsidian-skills — Official Agent Skills by Obsidian's CEO, So Agents Stop Breaking Your Vault
WonderLab
WonderLab

Posted on

Open Source Project of the Day (#112): obsidian-skills — Official Agent Skills by Obsidian's CEO, So Agents Stop Breaking Your Vault

#opensource #obsidian #agentskills #claude

Introduction

"Most agents treat Obsidian vaults as plain folders and don't understand Obsidian's syntax. They produce notes that either corrupt existing formatting or fail to render correctly in Obsidian."

This is article #148 in the Open Source Project of the Day series. Today's project is obsidian-skills — the official AI Agent skill collection written by Obsidian CEO Steph Ango (kepano).

You ask Claude Code to create some notes in your Obsidian vault. You open Obsidian and find: wikilinks written as [Note Name](note-name.md) instead of [[Note Name]], broken embed syntax, incorrectly formatted callouts, YAML frontmatter placed inside the body of the file instead of at the top.

This is a real friction point. AI agents don't know Obsidian's syntax extensions, default to standard Markdown handling, and produce format-corrupted files as a result. Obsidian's internal link-tracking system depends on [[wikilink]] format — use standard Markdown links and the note falls out of the link graph entirely.

obsidian-skills is the official answer. Written by Obsidian's CEO, released January 2026, 39.3k Stars — that number signals how strongly Obsidian power users want AI agents that actually understand their vault.

What You'll Learn

  • What typical errors AI agents make when operating on Obsidian vaults
  • What each of the 5 skills teaches agents: obsidian-markdown / obsidian-bases / json-canvas / obsidian-cli / defuddle
  • The detailed content of the obsidian-markdown SKILL.md: complete spec for wikilinks, embeds, callouts, and Properties
  • Installation for Claude Code, OpenCode, and Codex
  • defuddle: extracting clean Markdown from web pages to save tokens

Prerequisites

  • Regular Obsidian user (familiar with wikilinks, callouts, and basic concepts)
  • Experience with Claude Code or a similar AI coding tool
  • Interested in having AI help manage an Obsidian knowledge base

Project Background

What Is obsidian-skills?

obsidian-skills is a set of Agent Skills for Obsidian, following the agentskills.io open standard. It allows Claude Code, Codex, OpenCode, and other skills-compatible agents to correctly handle Obsidian-specific file formats.

"Correctly handle" is the operative phrase. Obsidian adds substantial syntax extensions on top of standard CommonMark Markdown — wikilinks, embeds, callouts, Properties, inline tags. These appear rarely in training data. Agents default to standard Markdown handling and produce format-corrupted files as a result.

Author

  • Author: Steph Ango (GitHub: kepano) — Obsidian CEO, creator of the Minimal theme
  • Why the author matters: This is the spec written by the person who built the format, not a third-party approximation
  • License: MIT
  • Released: January 2026

Project Stats

  • ⭐ GitHub Stars: 39,300+
  • 🍴 Forks: 2,800+
  • 📄 License: MIT

What AI Agents Get Wrong in Obsidian Vaults

Before installing obsidian-skills, here's what agents typically do with an Obsidian vault:

1. Wikilinks become standard links

# What agents write (wrong):
[Related Note](related-note.md)

# Correct Obsidian format:
[[Related Note]]
Enter fullscreen mode Exit fullscreen mode

Consequence: Obsidian's bidirectional link graph breaks. When you rename the note file, the link doesn't automatically update.

2. Embed syntax breaks

# What agents write (wrong):
![image](attachment.png)

# Correct Obsidian embed syntax:
![[attachment.png]]     ← embed a file
![[Note Name]]          ← embed another note inline
![[Note#Section]]       ← embed a specific section
Enter fullscreen mode Exit fullscreen mode

3. Callout format is wrong

# What agents write (wrong):
> **Note**: This is an important tip

# Correct Obsidian callout:
> [!note] Optional Title
> Callout content goes here
Enter fullscreen mode Exit fullscreen mode

4. Properties/frontmatter placement errors

Properties must be the first block in the file, wrapped in triple dashes. Agents frequently insert YAML metadata mid-file, or format it incorrectly causing Obsidian parsing failures.

All 5 Official Skills

Skill 1: obsidian-markdown

Purpose: Teaches agents the complete Obsidian Flavored Markdown specification.

The SKILL.md defines a 6-step workflow:

1. Add frontmatter (Properties)
2. Write body content
3. Link related notes with wikilinks
4. Embed content with ![[...]]
5. Add callouts for important information
6. Verify formatting (ensure correct rendering)
Enter fullscreen mode Exit fullscreen mode

Complete syntax coverage:

Internal Links (Wikilinks):

[[Note Name]]                   ← basic wikilink
[[Note Name|Display Text]]      ← custom display text
[[Note Name#Heading]]           ← link to specific heading
[[Note Name#^block-id]]        ← link to specific block
Enter fullscreen mode Exit fullscreen mode

Embeds:

![[Note Name]]                  ← embed full note
![[image.png]]                  ← embed image
![[document.pdf#page=3]]        ← embed specific PDF page
Enter fullscreen mode Exit fullscreen mode

Callouts:

> [!note] Optional Title
> Callout content

> [!warning]- Collapsed callout
> This callout is collapsed by default

> [!tip]+ Expanded callout
> This callout is expanded by default
Enter fullscreen mode Exit fullscreen mode

Types: note, warning, tip, info, success, question, failure, bug, quote

Properties (YAML frontmatter):

---
tags: [tag1, tag2]
aliases: [alias1, alias2]
cssclasses: [custom-class]
created: 2026-07-02
---
Enter fullscreen mode Exit fullscreen mode

Other Obsidian extensions:

  • Inline tags: #tag, #nested/tag
  • Hidden comments: %%This is hidden in Preview mode%%
  • Highlight: ==highlighted text==
  • LaTeX math: inline $formula$, block $$formula$$
  • Mermaid diagrams (with Obsidian note linking support)

Key rule the skill enforces: Use [[wikilinks]] for vault-internal notes (Obsidian tracks renames automatically); use standard Markdown links only for external URLs.

Skill 2: obsidian-bases

Purpose: Teaches agents to create and edit .base files — Obsidian's native database view format.

.base files let you query and display vault notes as a database:

Coverage:
- Creating and editing views (table view, gallery view, etc.)
- Setting filter conditions (by tags, dates, Properties fields)
- Defining formulas (spreadsheet-like calculations)
- Configuring summaries (aggregate statistics)
Enter fullscreen mode Exit fullscreen mode

This is a relatively new Obsidian feature (native database views) with almost no coverage in agent training data. The skill is currently one of the most authoritative format specifications available.

Skill 3: json-canvas

Purpose: Teaches agents to create and edit .canvas files — Obsidian's whiteboard format, also the JSON Canvas open standard.

{
  "nodes": [
    {"id": "node1", "type": "text", "text": "Idea A", "x": 0, "y": 0, "width": 200, "height": 100},
    {"id": "node2", "type": "file", "file": "Related Note.md", "x": 300, "y": 0, "width": 200, "height": 100}
  ],
  "edges": [
    {"id": "edge1", "fromNode": "node1", "toNode": "node2"}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Agents can create complex mind maps and knowledge visualizations programmatically rather than through GUI drag-and-drop.

Skill 4: obsidian-cli

Purpose: Teaches agents to interact with Obsidian vaults via command line and develop plugins and themes.

Covers:

  • Batch file operations in the vault
  • Obsidian URI protocol for triggering operations
  • Plugin development directory structure and API conventions
  • Theme development CSS variables and specifications

Skill 5: defuddle

Purpose: Extract clean Markdown content from web pages, removing ads, navigation, and sidebars — specifically designed to save tokens.

Input: A URL or raw HTML (contains ads, nav menus, sidebars)
Output: Clean Markdown body content

Use cases:
  "Save this article to my vault"
  → Agent uses defuddle to extract clean content
  → Generates a correctly formatted Obsidian note
  → Doesn't stuff the full noisy HTML into context
Enter fullscreen mode Exit fullscreen mode

Defuddle is also an independent open-source project (kepano/defuddle). The skill in obsidian-skills teaches agents how to invoke it.

Deep Dive

Why 39.3k Stars for Five Markdown Files

That number for what is essentially five SKILL.md files signals several things:

Obsidian's user demographics: Obsidian's core users are enthusiastic about knowledge management and tool integration, and among the earliest adopters of AI agent workflows.

A real pain point: AI agents corrupting Obsidian vault formatting had been a community frustration for a long time. The official answer spread quickly.

Author credibility: Written by Obsidian's CEO means the format specifications are authoritative, not community-approximated. Every nuance is intentional.

Installation

Claude Code (recommended):

Place the repository contents in a /.claude folder at the vault root:

# Navigate to your Obsidian vault root
cd /path/to/your/vault

# Clone into .claude directory
git clone https://github.com/kepano/obsidian-skills .claude/skills/obsidian-skills
Enter fullscreen mode Exit fullscreen mode

Or with npx:

npx skills add https://github.com/kepano/obsidian-skills
Enter fullscreen mode Exit fullscreen mode

OpenCode:

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills
Enter fullscreen mode Exit fullscreen mode

Important: clone the full repository, not just the inner skills/ directory. The path needs to resolve as ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md.

Marketplace (in supported agents):

/plugin marketplace add kepano/obsidian-skills
Enter fullscreen mode Exit fullscreen mode

Skill Auto-Activation

After installation, agents don't need to be told which skill to use. When the task involves Obsidian file operations, the relevant skill loads automatically:

You say: "Create today's daily note in vault/daily-notes/,
         with today's todos and meeting notes, linking to relevant project notes"

Agent detects Obsidian file operation
    ↓
Automatically loads obsidian-markdown SKILL.md
    ↓
Generates according to skill spec:
  - YYYY-MM-DD.md filename
  - Properties frontmatter with tags and date fields
  - [[Project Note Name]] wikilink format
  - Correctly formatted callouts for important items
Enter fullscreen mode Exit fullscreen mode

Relationship to the Agent Skills Ecosystem

obsidian-skills follows the agentskills.io open standard — the same format used by android/skills (Google's official Android dev skills), agent-skills (Addy Osmani's engineering discipline skills), and others.

This means:

  • The same skill files work across Claude Code, Codex, and OpenCode without modification
  • Any new tool supporting the Agent Skills standard works immediately

Real Use Cases

Use case 1: Research archiving

"Save the content of this URL to vault/research/,
 extract key points, mark them with callouts,
 and link to related existing notes"

→ Agent uses defuddle to extract clean Markdown
→ Uses obsidian-markdown spec to generate correctly formatted note
→ Automatically creates wikilinks to related notes
Enter fullscreen mode Exit fullscreen mode

Use case 2: Knowledge visualization

"Scan my vault notes on machine learning,
 create a .canvas mind map visualizing their relationships"

→ Agent uses obsidian-cli to read vault content
→ Uses json-canvas spec to generate .canvas file
→ Nodes and edges in correct format
Enter fullscreen mode Exit fullscreen mode

Use case 3: Format migration

"Convert all [Note Name](note.md) style links in my vault
 to Obsidian [[Note Name]] wikilink format"

→ Agent knows the correct wikilink syntax
→ Batch modification won't damage other link types
→ External URLs remain untouched
Enter fullscreen mode Exit fullscreen mode

Links and Resources

Conclusion

obsidian-skills has value at two levels.

At the surface: it fixes the specific problem of AI agents corrupting Obsidian formatting. Five skill files teach agents to use wikilinks, embeds, callouts, and Properties correctly. Your vault stops getting polluted by format-broken files written by AI.

At a deeper level: this is a signal from Obsidian's CEO that tools like Obsidian are beginning to treat AI agents as first-class citizens. Personal knowledge bases are evolving into infrastructure that agents can read and write, not just places you type into.

For heavy Obsidian users, this skill is close to essential. It transforms Claude Code from "a tool that might break your vault formatting" into "an assistant that can genuinely help manage your second brain."

Explore PrimeSkills — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.

Welcome to my Homepage for more useful insights and interesting products.

Top comments (0)