跪拜 Guibai
← Back to the summary

Obsidian's CEO Wrote the Official AI Agent Skills to Stop LLMs From Corrupting Your Vault

Introduction

"Most Agents treat an Obsidian vault as a regular folder and don't understand Obsidian's syntax conventions. This means the 'notes' they write either corrupt existing formatting or simply can't render properly in Obsidian."

This is the 148th article in the "One Open-Source Project a Day" series. Today's subject is obsidian-skills — an official collection of AI Agent Skills hand-written by Obsidian CEO Steph Ango (kepano).

You ask Claude Code to create some notes in your Obsidian vault, then open Obsidian to find: wikilinks written as [Note Name](note-name.md) instead of [[Note Name]], embed syntax completely wrong, callouts missing correct formatting, and Properties YAML frontmatter dumped into the body of the file…

This is a real pain point: AI Agents haven't learned Obsidian's proprietary syntax extensions and default to standard Markdown processing, producing malformed files. Obsidian's internal link-tracking system depends on the [[wikilink]] format; using standard Markdown links disconnects them from Obsidian's link graph.

obsidian-skills is the official answer. Written by the Obsidian CEO himself, released in January 2026, with 39.3k Stars — that number shows how intense the demand is among heavy Obsidian users for an AI Agent that truly understands a vault.

What You'll Learn

Prerequisites

Project Background

Project Introduction

obsidian-skills is a collection of Agent Skills designed specifically for Obsidian, following the agentskills.io open standard. It enables AI Agents that support Skills — such as Claude Code, Codex, and OpenCode — to correctly handle Obsidian-specific file formats.

"Correctly handle" is the key phrase. Obsidian adds a large number of extended syntax features on top of standard CommonMark Markdown — wikilinks, embeds, callouts, Properties, inline tags… These syntaxes have a very low representation in training data, so AI Agents haven't learned them well and default back to standard Markdown processing, resulting in format-corrupted files.

Author Introduction

Project Data

Typical Mistakes AI Agents Make When Operating on Obsidian

Before installing obsidian-skills, an Agent handles an Obsidian vault like this:

1. Wikilinks become standard links

# What the Agent writes (wrong):
[Related Note](related-note.md)

# Correct Obsidian format:
[[Related Note]]

Consequence of using standard links: Obsidian's bidirectional link graph breaks, and links won't auto-update when files are renamed.

2. Embed syntax errors

# What the Agent writes (wrong):
![Image](attachment.png)

# Correct Obsidian embed:
![[attachment.png]]     ← Embed a file
![[Note Name]]          ← Embed another note
![[Note#Section]]       ← Embed a specific section

3. Callout formatting is wrong

# What the Agent writes (wrong):
> **Note**: This is an important reminder

# Correct Obsidian callout:
> [!note] This is the title
> Callout content goes here

4. Properties/frontmatter position is wrong

Properties must be the very first content block in the file, wrapped in triple dashes. Agents often mix YAML metadata into the body, or write the format incorrectly, causing Obsidian to fail parsing.

The 5 Official Skills

Skill 1: obsidian-markdown

Function: Teaches the Agent the complete specification of Obsidian Flavored Markdown.

The SKILL.md contains a 6-step workflow:

1. Add frontmatter (Properties)
2. Write body content
3. Link related notes using wikilinks
4. Embed content using embeds
5. Highlight important information using callouts
6. Verify formatting (ensure correct rendering)

Detailed specifications covered:

Internal Links (Wikilinks):

[[Note Name]]                    ← Basic wikilink
[[Note Name|Display Text]]       ← Custom display text
[[Note Name#Section Heading]]    ← Link to a specific section
[[Note Name#^block-id]]          ← Link to a specific block

Embeds:

![[Note Name]]                   ← Embed an entire note
![[Image.png]]                   ← Embed an image
![[Document.pdf#page=3]]         ← Embed a specific page of a PDF

Callouts:

> [!note] Optional Title
> Callout content

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

> [!tip]+ Expanded callout
> This callout is expanded by default

Available 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
---

Other Obsidian extended syntax:

Skill 2: obsidian-bases

Function: Teaches the Agent to create and edit .base files — Obsidian's native database view format.

.base files allow notes in a vault to be queried and displayed as a database:

Feature coverage:
- Create and edit views (table view, gallery view, etc.)
- Set filter conditions (filter by tags, dates, Properties fields)
- Define formulas (spreadsheet-like calculations)
- Configure summaries (aggregate statistics)

This is a relatively new Obsidian feature (native database), with almost no coverage in Agent training data. The Skill is currently one of the most authoritative format documents available.

Skill 3: json-canvas

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

// .canvas file format example
{
  "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"}
  ]
}

Agents can create complex mind maps and knowledge graphs programmatically, rather than just dragging and dropping in the GUI.

Skill 4: obsidian-cli

Function: Teaches the Agent to interact with an Obsidian vault via the command line, and to develop plugins and themes.

Scenarios covered:

Skill 5: defuddle

Function: Extracts clean Markdown content from web pages, removing noise like ads, navigation, and sidebars — designed specifically to save tokens.

Input: A URL or HTML content (containing ads, navigation menus, sidebars, etc.)
Output: Clean Markdown body text

Use case:
  "Save this article to my vault"
  → Agent uses defuddle to extract clean content
  → Generates a correctly formatted Obsidian note
  → No need to stuff the entire noisy HTML into the context

Defuddle also exists as an independent open-source project (kepano/defuddle). The Skill within obsidian-skills teaches the Agent how to invoke it.

Detailed Project Analysis

Why 39.3k Stars

This number is surprisingly high for a project that is "essentially 5 Markdown files," indicating several things:

Characteristics of the Obsidian user base: Obsidian's core users have a high enthusiasm for knowledge management and tool integration, and are among the earliest adopters of AI Agent tools.

The authenticity of the need: The problem of AI corrupting Obsidian vault formatting is a pain point long discussed in the Obsidian user community. The official solution spread rapidly upon release.

The signal of authorship: Being hand-written by the Obsidian CEO means this isn't an approximation figured out by the community, but a specification written based on the most authoritative understanding of the format.

Installation Methods

Claude Code (Recommended):

Place the repository contents into the /.claude folder at the root of your vault:

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

# Clone into the .claude directory
git clone https://github.com/kepano/obsidian-skills .claude/skills/obsidian-skills

Or use npx:

npx skills add https://github.com/kepano/obsidian-skills

OpenCode:

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

Note: Clone the entire repository, not just the internal skills/ directory, otherwise path resolution will fail.

Marketplace (within supported Agents):

/plugin marketplace add kepano/obsidian-skills

Automatic Skill Activation

After installation, the Agent doesn't need you to manually specify which Skill to use each time. When it detects a task involving Obsidian-related operations, the Agent automatically loads the corresponding Skill:

You say: "Create today's daily note in my vault's daily-notes folder,
         include today's to-dos and meeting notes, and link to related project notes"

Agent detects Obsidian file operations
    ↓
Automatically loads obsidian-markdown SKILL.md
    ↓
Generates according to Skill specification:
  - Correct YYYY-MM-DD.md filename
  - Properties frontmatter containing tags and date
  - Wikilinks to project notes using [[Project Note Name]] format
  - Correctly formatted callouts for important items

Relationship with the Agent Skill Ecosystem

obsidian-skills follows the agentskills.io open standard, using the same format as android/skills (Google's official Android development Skill) and agent-skills (Addy Osmani's engineering standards Skill).

This means:

Practical Use Cases

Scenario 1: Research Material Archiving

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

→ Agent uses defuddle to extract clean Markdown
→ Uses obsidian-markdown specification to generate correctly formatted notes
→ Automatically creates wikilinks pointing to related notes

Scenario 2: Knowledge Organization

"Scan the vault for notes about machine learning,
 create a .canvas mind map to visualize their relationships"

→ Agent uses obsidian-cli to read vault contents
→ Uses json-canvas specification to generate .canvas file
→ Nodes and edges generated in correct format

Scenario 3: Batch Format Migration

"Convert all standard Markdown links written as [Note](note.md) format
 in the vault to Obsidian's [[Note]] format"

→ Agent knows the correct wikilink syntax
→ Batch modification won't accidentally damage other link types
→ External links remain unaffected

Project Links and Resources

Summary

The value of obsidian-skills has two layers.

The surface layer: It solves the specific problem of AI Agents corrupting Obsidian formatting — 5 Skill files that teach an Agent to correctly use wikilinks, embeds, callouts, and Properties, so your vault is no longer polluted by AI-generated files with format errors.

The deeper layer: This is an official signal, hand-written by the Obsidian CEO — tools like Obsidian are starting to treat AI Agents as first-class citizens. Personal knowledge bases are becoming infrastructure that Agents can read and write, not just a place where you type things yourself.

For heavy Obsidian users, this Skill is almost mandatory: it transforms Claude Code from "a dangerous tool that corrupts vault formatting" into "an assistant that can truly help manage your second brain."

Explore PrimeSkills — a curated marketplace of AI Agents and skills, each verified through real enterprise workflows, stripping away the hype and leaving what's truly useful.

Welcome to visit my personal homepage to discover more valuable insights and interesting products.