Obsidian Skills: teach agents to actually work with your knowledge base

AI agents can write code and browse web pages. But ask one to edit your actual documents — good luck. No matter how smart Claude Code is, it has no idea how wikilinks work in your Obsidian vault, or how callouts nest inside list items, or what a valid properties block looks like. The agent gives you markdown that looks fine on its own but renders broken when you paste it into Obsidian.

Obsidian Skills fixes this. A 35k-star open-source project that teaches agents how to use Obsidian’s native formats. The core idea is simple: instead of writing a vague “you are a knowledge manager” prompt, give the agent an exact spec for each file type it might touch — the syntax rules, every parameter, every edge case. This isn’t a prompt engineering problem. It’s a knowledge injection problem.

Why you need this

You have hundreds of notes in your Obsidian vault. You want to use AI to do something useful with them: reorganize tags, extract summaries, generate database views, batch-format entries. You open Claude Code, tell it to convert your notes into structured data, and get back standard markdown. You paste it into Obsidian. Level-three headers are misaligned. Blockquotes are broken. Every link is rendered as a raw URL instead of a wikilink.

Agent Skills specification offered a systematic solution. It defines a standardized SKILL.md format that any compatible agent (Claude Code, Codex, OpenCode) can read and follow. Obsidian Skills is a canonical implementation: every Obsidian-specific file format gets its own set of rules, and the agent follows them exactly.

What’s included

Five skills ship with the project right now:

obsidian-markdown — Create and edit Obsidian Flavored Markdown (.md), including wikilinks ([[links]]), embeds (![[embeds]]), callouts (> [!info] blocks), frontmatter properties, and all Obsidian-specific markup the agent needs to know, not just a ballpark approximation that looks enough like markdown to be dangerous.

obsidian-bases — Create and edit Obsidian Bases files (.base). This is Obsidian’s Notion-like database feature. Covers view configuration, filter expressions, formula syntax, and summary aggregation functions. Agents produce .base files that run on first load.

json-canvas — Work with JSON Canvas files (.canvas). Canvas is Obsidian’s whiteboard with nodes, edges, groups, and connections. The skill encodes the canvas JSON schema so what the agent writes renders properly.

obsidian-cli — Interact with Obsidian vaults via the Obsidian CLI. Covers plugin development, theme development, and other programmatic operations through command-line interfaces.

defuddle — Extract clean markdown from web pages using Defuddle, stripping navigation, ads, scripts, and other noise to save tokens while preserving content structure and readability. This tool is also developed by kepano, which means real-world scraping experience behind it.

Installation

Three ways, pick whichever works:

# Marketplace (recommended)
/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

# npx method
npx skills add git@github.com:kepano/obsidian-skills.git

# Manual install (OpenCode)
git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

OpenCode auto-discovers all SKILL.md files under ~/.opencode/skills/. No config changes needed. Restart and they’re available immediately.

For Claude Code, copy repo contents into .claude at your vault root. For Codex, copy the skills/ directory to ~/.codex/skills.

How it differs from other approaches

Most tutorials say “tell the agent how wiki syntax works in your system prompt”. That roughly works until it doesn’t: system prompts eat context window fast, the more details you pack in the harder every conversation becomes, and every new agent means rewriting the whole thing from scratch.

Skill files solve this through on-demand loading. The agent only reads the relevant skill when it encounters a specific file type. Your main prompt stays lean. Switching between tasks stops consuming dozens of kilobytes of system text. And unlike monolithic prompt files maintained by memory alone, shared SKILL.md files enforce consistency across teams and sessions. Quality stays controllable. That matters when three people are editing the same vault.

Where it shines

• Personal knowledge automation: batch reformatting, auto-tagging, index generation
• Content production pipelines: collect → organize → publish workflow automation
• Team collaboration: unified note format and metadata conventions
• Plugin/theme development assisted by CLI skill capabilities

Things to watch out for

Obsidian updates frequently. Edge-case OFM behaviors may shift between versions. If an agent generates a perfectly valid callout that fails to render in a recent Obsidian release, check version compatibility first. JSON Canvas schema is still evolving too — validate the output in Obsidian before trusting it blindly.

Project maintenance is solid with recent commits within weeks. Star growth is fast and issue response is reasonable given solo maintainer pace.

Agents don’t automatically understand your tools. They need explicit rules, not vague task descriptions. Obsidian Skills’ value isn’t in being groundbreaking — it’s in doing something obvious systematically and cleanly.

Quick install cheat sheet

# OpenCode (recommended)
git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

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

# Any other Agent Skills-compatible tool
cp -r obsidian-skills/skills/* ~/.YOUR_AGENT/skills/

Next time your AI agent manages your knowledge base, don’t just append another prompt section. Install a skill.

GitHub: https://github.com/kepano/obsidian-skills License: MIT