obsidian-skills: Teach Claude Code How to Work with Obsidian

I keep my second brain in Obsidian on the same Rocky Linux system I use for everything else. For months, I let Claude Code work with my notes without telling it how Obsidian actually works.

It would create regular Markdown links instead of wikilinks, ignore callout blocks, and have no idea what a .base file was when it came across one. The notes still opened in Obsidian, but they lost the features that make Obsidian so useful.

Then I found obsidian-skills, a small repository maintained by Steph Ango, the CEO of Obsidian (known as kepano on GitHub). It packages Obsidian-specific knowledge into Agent Skills. After adding it to my vault’s Claude Code setup, I noticed the difference immediately.

Claude started creating proper wikilinks, respected my Bases filters, and even used the Defuddle skill to pull clean Markdown from web pages instead of dumping raw HTML into my notes.

In this article, I’ll show you what obsidian-skills includes, how to install it on Ubuntu/Debian and RHEL/Rocky Linux, and how to verify that your agent is actually using it instead of letting it sit unused in a folder.

What obsidian-skills Actually Does

obsidian-skills is not an Obsidian plugin that you install from the Community Plugins browser. Instead, it’s a collection of Agent Skills—plain text instruction files that follow the open Agent Skills specification.

These files are designed to be read by an AI coding agent before it starts working with your vault. Tools like Claude Code, Codex, and OpenCode support this format out of the box.

The repository currently includes five skills, and each one teaches your AI agent a specific part of how Obsidian works:

• obsidian-markdown – Explains Obsidian Flavored Markdown, including wikilinks, embeds, callouts, and YAML properties, which behave differently from standard Markdown.
• obsidian-bases – Teaches the .base file format used to create filtered and formula-driven views of your notes.
• json-canvas – Covers the open .canvas format used by Obsidian’s Canvas feature, including nodes, edges, and groups.
• obsidian-cli – Shows the agent how to use the Obsidian CLI, including tasks related to plugin and theme development.
• defuddle – Helps the agent extract clean Markdown from web pages instead of pasting large amounts of raw HTML into your notes.

Without these skills, an AI agent sees your vault as nothing more than a collection of plain text files. With them, it understands the syntax and structure that power Obsidian’s links, queries, and canvas features.

Prerequisites

Before you begin, make sure you have:

• A Linux system with Git installed.
• Node.js and npm are installed (only needed if you plan to use the npx installer or the Claude Code plugin marketplace command).
• Claude Code, Codex, or OpenCode is already installed and working.
• An existing Obsidian vault, since these skills are designed to work alongside one.

If you already use Claude Code with an Obsidian vault, you’re mostly ready to go. The Node.js requirement only applies to one of the installation methods covered next.

Step 1: Confirm Git and Node.js Are Installed

Before choosing an installation method, check whether Git and Node.js are already installed. The quickest installation method (npx skills) requires Node.js, while the manual installation method only needs Git.

git --version
node --version

Example output:

git version 2.43.0
v20.14.0

If either command returns command not found, install the missing packages first.

On Ubuntu/Debian

sudo apt update
sudo apt install git nodejs npm -y

On RHEL/Rocky Linux

sudo dnf install git nodejs npm -y

Here, sudo runs the command with administrative privileges, which are required when installing software packages on your system.

Step 2: Choose Your Installation Method

obsidian-skills offers three installation methods. If you only use Claude Code, Method A is the quickest because it requires the least setup.

Method A: Install from the Claude Code Plugin Marketplace

This is the fastest option if Claude Code is your only AI agent. Run these commands inside Claude Code, not in your regular Linux terminal:

/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

Here’s what each command does:

• plugin marketplace add kepano/obsidian-skills adds the GitHub repository as a plugin source that Claude Code can use.
• plugin install obsidian@obsidian-skills installs the obsidian plugin from that marketplace source.

Because these are Claude Code slash commands, you won’t see normal terminal output. Instead, Claude Code will display a confirmation message in the chat once the installation is complete.

Method B: Use the npx skills Installer

This method runs from your normal Linux terminal and works regardless of which AI agent you’re using. Instead of installing everything automatically, it walks you through an interactive setup.

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

Example output:

Source: https://github.com/kepano/obsidian-skills.git
◇  Repository cloned
◇  Found 5 skills
◇  Select skills to install (space to toggle)
◆  Which agents do you want to install to?

The installer pauses at two prompts, and both require your input:

• Select skills to install: Press the Space key to select all five skills (defuddle, json-canvas, obsidian-bases, obsidian-cli, and obsidian-markdown), and then press Enter. Since the skills work together to improve how your agent handles Obsidian content, there’s little reason to skip any of them.
• Which agents do you want to install to?: The installer supports 73 different agents, and only a few appear on the screen at a time. Although the Universal (.agents/skills) group is selected automatically, Claude Code may not be visible initially. Type claude in the search field, select Claude Code by pressing Space, and then press Enter to continue.

After the installation completes, verify that the skills were installed:

ls -la /path/to/your/obsidian-vault/.claude

Example output:

defuddle  json-canvas  obsidian-bases  obsidian-cli  obsidian-markdown

If the .claude directory is empty or doesn’t exist, check the .agents/skills directory instead, as some versions of the installer place the files there.

Method C: Manually Clone the Repository (Claude Code, Codex, or OpenCode)

I prefer this method because I can see exactly what gets copied and where it ends up. It also works consistently whether you’re using Claude Code, Codex, or OpenCode.

For Claude Code

Move into your Obsidian vault and clone the repository into a .claude directory:

cd /path/to/your/obsidian-vault
git clone https://github.com/kepano/obsidian-skills.git .claude

Example output:

Cloning into '.claude'...
remote: Enumerating objects: 210, done.
remote: Counting objects: 100% (210/210), done.
Receiving objects: 100% (210/210), 84.30 KiB | 2.11 MiB/s, done.

Here’s what these commands do:

• cd /path/to/your/obsidian-vault moves you into your Obsidian vault. This step is important because it determines where the .claude directory will be created.
• git clone .claude clones the repository directly into a folder named .claude instead of creating a folder named obsidian-skills.

For Codex

Clone the repository temporarily and copy only the skills/ directory into Codex’s skills location:

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

For OpenCode

Clone the entire repository into OpenCode’s skills directory:

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

Copying only the skills/ subdirectory breaks this layout, and OpenCode won’t load the skills correctly. After cloning, restart OpenCode because it only discovers new skills when it starts up.

Step 3: Verify That Claude Code Is Reading the Skills

Installing the files doesn’t automatically mean Claude Code is using them. It’s a good idea to verify that the skills were loaded correctly.

Start a Claude Code session from inside your Obsidian vault:

claude

Once the session starts, ask Claude Code a simple question:

What Obsidian-specific skills do you have access to right now?

If everything is set up correctly, Claude Code should mention these skills by name:

• obsidian-markdown
• obsidian-bases
• json-canvas
• obsidian-cli
• defuddle

It will usually include a brief description of what each skill does.

If Claude Code responds as if it doesn’t know anything about Obsidian-specific syntax, the skills are probably not being loaded. The two most common causes are:

• The directory name is incorrect. It must be named exactly .claude.
• You started Claude Code from outside your vault’s root directory, so it couldn’t find the .claude folder.

Once Claude Code recognizes the skills, it can work with your vault using Obsidian’s syntax and features instead of treating everything as plain text files.

Step 4: Put a Skill to Work

The easiest way to see the benefit of obsidian-skills is to give Claude Code a task that requires Obsidian-specific knowledge. These are the kinds of tasks that a regular Markdown-aware AI agent often gets wrong.

For example, I tested it with a Base file I wanted to create for tracking the status of my Pro TecMint course chapters.

Inside Claude Code, I used this prompt:

Create an Obsidian Base file that filters notes tagged #course-chapter and groups them by a "status" property with values Draft, Review, and Published.

With the obsidian-bases skill loaded, Claude Code generated a valid .base file with the correct filter and grouping structure on the first try.

Without the skill, it would typically guess at the syntax and produce something that looks reasonable but doesn’t actually work with Obsidian’s Bases feature.

Keeping obsidian-skills Updated

obsidian-skills is actively maintained, and new skills and fixes are added regularly. If you installed it by manually cloning the repository, update it just like any other Git repository:

cd ~/vault-path/.claude
git pull origin main

This moves into your .claude directory and pulls the latest changes from the main branch.

If you installed obsidian-skills through the Claude Code plugin marketplace, you don’t need to run git pull. In that case, updates are handled through Claude Code’s own plugin update mechanism because Claude Code manages the files for you.

Conclusion

At this point, obsidian-skills has given your AI agent the knowledge it needs to understand how your Obsidian vault works instead of treating it as a collection of plain text files. That may sound like a small improvement, but it makes a noticeable difference in everyday use.

A wikilink that resolves correctly, a Base file that Obsidian accepts without errors, or a Canvas file with properly structured nodes and edges all depend on the agent understanding Obsidian’s formats from the start. That means less time fixing mistakes and more time working with your notes.

Try the defuddle skill the next time you save an article to your vault and compare it with your usual copy-and-paste workflow. You’ll likely notice the difference immediately because the resulting note is much cleaner and contains far less clutter.

If you’ve gone a step further and created custom skills for your own workflow, such as supporting a specific Obsidian plugin or a custom file format, I’d genuinely love to hear how you approached it.