Obsidian Agent Skills: Let Claude Code Control Your Vault (2026 Setup Guide)

The CEO of Obsidian just open-sourced the official way to let AI agents control your vault.

It's called obsidian-skills — a set of five agent skill files written by Steph Ango (kepano), Obsidian's creator. They teach Claude Code, Codex CLI, and OpenCode exactly how Obsidian works: the syntax, the CLI, the canvas format, and even how to extract clean web content for import. The repo went GitHub trending this week.

If you use Obsidian for notes, writing, or knowledge management and you also use AI coding agents — this is the missing glue.

---

What Are Agent Skills?

Agent skills are instruction files that tell an AI agent how to work within a specific domain. They follow the Agent Skills specification, a community standard that's gaining adoption across tools like Claude Code, Codex CLI, and OpenCode.

Each skill is a SKILL.md file — a structured markdown document that the AI reads before taking actions. It describes the syntax, file formats, idioms, and edge cases the agent needs to know to work correctly in that environment.

Think of it like an onboarding doc written specifically for an AI, not a human.

Without skills, Claude Code might try to create a note in Obsidian and write # Title instead of using YAML frontmatter properties. It might not know that [[wikilinks]] are how internal links work, or that callouts use a specific > [!note] syntax. Skills fix all of that.

The obsidian-skills repo is notable because it's not a third-party project — it's built by Obsidian's own CEO. These are the canonical, official skill definitions.

---

The 5 Official Skills

1. obsidian-markdown

Teaches the agent to write Obsidian Flavored Markdown correctly. This is not standard markdown — Obsidian has extensions that most AI models get wrong by default:

• [[wikilinks]] for internal page links
• ![[image.png]] for file embeds
• > [!note], > [!warning], > [!tip] for callouts
• YAML frontmatter with typed properties (date:, tags:, custom fields)
• Nested tags like #project/client-name

This skill is the foundation. Everything else builds on correct markdown syntax.

2. obsidian-bases

Covers Obsidian Bases — the database-style feature that lets you create structured views over your vault's notes. With this skill, an agent can:

• Create .base files with filtered views of your notes
• Write formulas and summaries across note properties
• Build dashboards that surface patterns in your knowledge base
• Query across notes without manual linking

This opens up workflows like "show me all notes tagged #project with status: active" — and have the AI generate and maintain that view for you.

3. json-canvas

JSON Canvas is an open format for infinite canvas files (.canvas extension in Obsidian). This skill teaches the agent the exact JSON schema:

• Adding nodes: text nodes, file nodes, group nodes, URL nodes
• Drawing edges with directional connections and labels
• Organizing nodes into groups with colors and labels
• Reading and modifying existing canvas files

Practical use: ask your AI to map out a project canvas, generate a visual outline of a document, or create a knowledge map from a set of linked notes.

4. obsidian-cli

Covers the Obsidian CLI — a command-line tool for vault operations. This skill enables:

• Opening specific vaults and files programmatically
• Installing and managing plugins and themes from the terminal
• Triggering vault-level operations through scripts
• Bridging between what the AI wants to do and the actual Obsidian application

This is the most powerful skill for automation workflows — it lets the agent actually launch actions in Obsidian, not just edit files.

5. defuddle

Defuddle is a web content extraction tool that strips pages down to clean, readable markdown. It removes ads, navigation, sidebars, and clutter — outputting just the content.

Why is this a vault skill? Because importing web content into Obsidian is a common workflow, and raw HTML is token-expensive and messy. With defuddle, the agent can fetch a URL, clean it, and save a lean markdown note in one step.

---

Setup: Install in Your Vault

Option 1: npx (Fastest — Any Agent)

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

This is the fastest install path. The npx skills CLI handles placing the skill files in the right location for your configured agent.

Option 2: Claude Code

Claude Code looks for skills in a /.claude/ folder at the root of whatever directory it's working in.

1. Open your Obsidian vault's folder in your terminal
2. Create the .claude directory if it doesn't exist:

   mkdir -p .claude
   

3. Clone the skills into it:

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

4. Copy just the skills/ contents into .claude/:

   cp -r .claude/obsidian-skills/skills/* .claude/
   

5. Start Claude Code from your vault root:

   claude
   

Skills load automatically. You can verify by asking Claude: "What Obsidian skills do you have loaded?"

Option 3: Codex CLI

# Create the skills directory if it doesn't exist
mkdir -p ~/.codex/skills

# Copy the skills
git clone https://github.com/kepano/obsidian-skills.git /tmp/obsidian-skills
cp -r /tmp/obsidian-skills/skills/* ~/.codex/skills/

# Restart Codex CLI

Option 4: OpenCode

OpenCode auto-discovers SKILL.md files under ~/.opencode/skills/. Clone the full repo — don't copy just the inner folder:

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

Restart OpenCode. No config file changes needed — skills are discovered automatically.

---

What You Can Actually Do With This

Once skills are loaded, your agent understands Obsidian natively. Here are practical workflows:

Automated daily notes

"Create a daily note for today with these sections: Morning priorities, 
Meeting notes, Evening review. Use my standard frontmatter template."

The agent will use correct YAML properties, Obsidian date formatting, and wikilinks — not generic markdown.

Knowledge base organization

"Scan my /Projects folder, identify notes missing a status property, 
and add status: active to all of them."

The agent can read real files in your vault, understand the Obsidian property format, and make batch edits correctly.

Research import with defuddle

"Fetch this URL, extract the clean content with defuddle, and save it 
as a note in my /Reading List folder with today's date and source URL."

No more manually copying content from web pages into your vault.

Canvas generation

"Create a canvas file showing the relationship between these 5 projects 
with color-coded groups by priority."

The agent writes a valid .canvas JSON file your vault opens natively.

Plugin-assisted workflows

"Install the Dataview plugin via the Obsidian CLI, then create a 
Dataview query note that shows all tasks due this week."

---

Why This Matters Beyond Obsidian

The broader signal here is the Agent Skills specification gaining real adoption. When the CEO of a major productivity tool builds official skills for their own product, it validates the standard.

We're heading toward a world where every major tool ships an official SKILL.md — telling AI agents exactly how to work with that software. Obsidian is one of the first. This is a pattern that will likely spread to Notion, Linear, VS Code plugins, and more.

If you build tools for a living — or if you're learning to work with AI coding agents — understanding the Agent Skills spec now is the right move. New to command line tools? Our terminal beginners guide walks through everything you need to get comfortable.

---

Performance Note: Running AI Agents Locally

Claude Code and Codex CLI both connect to cloud APIs by default. If you're working with sensitive vault contents — personal notes, business data, private research — you may want to run a local model instead.

For local agent setups, you'll need capable hardware. Check our VRAM guide to see whether your machine can handle it. If you need cloud GPU access for testing larger models before committing to local hardware, Ampere offers affordable per-hour GPU instances with no long-term commitment.

---

Frequently Asked Questions

Do I need to pay for this? No. The obsidian-skills repo is free and open source (MIT license). Obsidian itself is free for personal use. The AI agent (Claude Code, Codex CLI, etc.) is separate — Claude Code requires an Anthropic API key, Codex CLI requires an OpenAI API key. Local model alternatives exist that are completely free after setup.

Will this work with the free version of Obsidian? Yes. All five skills work with Obsidian's free tier. Obsidian Sync and Publish are paid features, but the vault operations covered by these skills don't require them.

Can I use this with ChatGPT? Not directly via the standard Agent Skills spec. The spec is primarily implemented in Claude Code, Codex CLI, and OpenCode. ChatGPT doesn't currently support the Agent Skills format natively, though you can manually paste skill content into a custom GPT's system instructions as a workaround.

Does the agent need to have Obsidian installed? For the obsidian-cli skill, yes — the CLI communicates with the running Obsidian application. For the other skills (markdown, bases, canvas, defuddle), the agent just needs read/write access to your vault folder. The files are plain text and JSON.

What if I use a different note app? The obsidian-markdown, obsidian-bases, and json-canvas skills are Obsidian-specific. The defuddle skill works anywhere — it's just a web extraction tool that happens to output markdown. If you're on Logseq, Notion, or another PKM, look for community-built skills for those platforms.

Is my vault content sent anywhere? Only the contents you explicitly include in your prompts are sent to the AI provider's API. The agent reads files locally. It doesn't bulk-upload your vault. That said, anything you paste into a Claude Code prompt goes to Anthropic's servers — use a local model if full privacy is required.

---

Get Started

Install the skills now:

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

Then start Claude Code from your vault root and try:

"Using the Obsidian skills you have, create a new note about my current 
project with proper frontmatter, a summary section, and three action items."

The obsidian-skills repo is at github.com/kepano/obsidian-skills. It's actively maintained by Obsidian's own team — expect it to stay current as Obsidian evolves.