Obsidian Skills for AI Agents

---
name: obsidian-skills-agent
description: Teach AI coding agents to work with Obsidian vaults using Markdown, Bases, JSON Canvas, and the Obsidian CLI
triggers:
  - work with obsidian vault
  - create obsidian notes
  - edit obsidian markdown
  - use obsidian bases
  - create json canvas
  - interact with obsidian cli
  - add obsidian agent skills
  - teach agent obsidian syntax
---

# Obsidian Skills for AI Agents

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

`obsidian-skills` is a collection of agent skills that teach AI coding agents (Claude Code, Codex CLI, OpenCode, Cursor, etc.) how to work with Obsidian vaults. It covers Obsidian Flavored Markdown, Bases, JSON Canvas, and the Obsidian CLI — following the [Agent Skills specification](https://agentskills.io/specification).

---

## Installation

### Via Marketplace (if supported)

/plugin marketplace add kepano/obsidian-skills

/plugin install obsidian@obsidian-skills

### Via npx

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

### Claude Code (Manual)

Copy the repo contents into a `/.claude` folder at the root of your Obsidian vault:

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

### Codex CLI (Manual)

Copy the `skills/` directory into your Codex skills path:

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

cp -r /tmp/obsidian-skills/skills/* ~/.codex/skills/

### OpenCode (Manual)

Clone the full repo into the OpenCode skills directory:

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

> Do **not** copy only the inner `skills/` folder. Clone the full repo so the path resolves to:
> `~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md`
>
> OpenCode auto-discovers all `SKILL.md` files under `~/.opencode/skills/`. Restart OpenCode after cloning.

---

## Available Skills

| Skill | File | Description |
|---|---|---|
| `obsidian-markdown` | `skills/obsidian-markdown/SKILL.md` | Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties |
| `obsidian-bases` | `skills/obsidian-bases/SKILL.md` | Obsidian Bases (`.base`) with views, filters, formulas, summaries |
| `json-canvas` | `skills/json-canvas/SKILL.md` | JSON Canvas (`.canvas`) with nodes, edges, groups, connections |
| `obsidian-cli` | `skills/obsidian-cli/SKILL.md` | Obsidian CLI for vault, plugin, and theme interaction |
| `defuddle` | `skills/defuddle/SKILL.md` | Extract clean markdown from web pages using Defuddle |

---

## Obsidian Flavored Markdown

Obsidian uses a superset of standard Markdown. Key syntax additions:

### Properties (Frontmatter)

---

title: My Note

tags:

- research

- ai

date: 2026-03-01

status: draft

aliases:

- My Research Note

---

### Wikilinks

[[Note Name]]

[[Note Name|Display Text]]

[[Folder/Note Name]]

[[Note Name#Heading]]

### Embeds

![[Note Name]]

![[image.png]]

![[Note Name#Section]]

![[Note Name#^block-id]]

### Callouts

> [!note]

> This is a note callout.

> [!warning] Custom Title

> This is a warning with a custom title.

> [!tip]- Collapsible Tip

> This callout is collapsible by default (closed).

> [!info]+ Expanded Collapsible

> This callout is collapsible and starts open.

Callout types: `note`, `abstract`, `info`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`

### Block IDs

This paragraph has a block ID. ^my-block-id

Reference with: `[[Note#^my-block-id]]`

### Tags

#tag

#nested/tag

#multi-word-tag

---

## Obsidian Bases (`.base` files)

Bases are database-like views over your vault's markdown files, using `.base` file format.

### Basic Base File

# my-projects.base

view: table

filter:

type: eq

field: type

value: project

fields:

- name

- status

- due

- priority

sort:

- field: due

order: asc

### Views

view: table # Spreadsheet-style

view: list # Simple list

view: board # Kanban-style (requires groupBy)

view: gallery # Card/image grid

view: calendar # Calendar (requires date field)

### Filters

# Single filter

filter:

type: eq

field: status

value: active

# Compound filter

filter:

type: and

conditions:

- type: eq

field: type

value: project

- type: neq

field: status

value: archived

Filter operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`

### Formulas

fields:

- name: days_remaining

formula: "dateDiff(now(), due, 'days')"

- name: full_name

formula: "concat(first_name, ' ', last_name)"

### Summaries

summary:

- field: budget

type: sum

- field: status

type: count_by_value

---

## JSON Canvas (`.canvas` files)

JSON Canvas is an open format for infinite canvas data. Files use the `.canvas` extension.

### Minimal Canvas

{

"nodes": [

{

"id": "node1",

"type": "text",

"x": 0,

"y": 0,

"width": 250,

"height": 100,

"text": "Hello, Canvas!"

}

],

"edges": []

}

### Node Types

{

"nodes": [

{

"id": "text-node",

"type": "text",

"x": 0, "y": 0,

"width": 250, "height": 100,

"text": "## Markdown content\nSupports **bold**, *italic*, [[wikilinks]]"

},

{

"id": "file-node",

"type": "file",

"x": 300, "y": 0,

"width": 400, "height": 300,

"file": "Notes/My Note.md"

},

{

"id": "link-node",

"type": "link",

"x": 0, "y": 200,

"width": 400, "height": 200,

"url": "https://obsidian.md"

},

{

"id": "group-node",

"type": "group",

"x": -50, "y": -50,

"width": 600, "height": 400,

"label": "My Group",

"background": "#ff6b6b",

"backgroundStyle": "solid"

}

]

}

### Edges (Connections)

{

"edges": [

{

"id": "edge1",

"fromNode": "node1",

"fromSide": "right",

"toNode": "node2",

"toSide": "left",

"label": "connects to",

"color": "#ff0000"

}

]

}

Edge sides: `top`, `right`, `bottom`, `left`

### Node Colors

{

"color": "1"

}

Preset colors: `"1"` (red), `"2"` (orange), `"3"` (yellow), `"4"` (green), `"5"` (cyan), `"6"` (purple)
Custom: `"color": "#ff6b6b"`

### Full Canvas Example

{

"nodes": [

{

"id": "idea-central",

"type": "text",

"x": 200,

"y": 200,

"width": 300,

"height": 150,

"color": "4",

"text": "# Central Idea\nThe core concept here."

},

{

"id": "note-ref",

"type": "file",

"x": 600,

"y": 100,

"width": 400,

"height": 300,

"file": "Research/Background.md"

},

{

"id": "web-ref",

"type": "link",

"x": -200,

"y": 150,

"width": 350,

"height": 200,

"url": "https://example.com/source"

}

],

"edges": [

{

"id": "e1",

"fromNode": "idea-central",

"fromSide": "right",

"toNode": "note-ref",

"toSide": "left",

"label": "supported by"

},

{

"id": "e2",

"fromNode": "web-ref",

"fromSide": "right",

"toNode": "idea-central",

"toSide": "left",

"label": "references"

}

]

}

---

## Obsidian CLI

The Obsidian CLI lets you interact with vaults programmatically.

### Common Commands

# Open a vault

obsidian open /path/to/vault

# Open a specific note

obsidian open /path/to/vault --file "Notes/My Note.md"

# Create a new note

obsidian new /path/to/vault --file "Notes/New Note.md" --content "# New Note"

# List all notes in vault

obsidian list /path/to/vault

# Search vault

obsidian search /path/to/vault --query "search term"

# Install a plugin

obsidian plugin install /path/to/vault --id dataview

# Enable a plugin

obsidian plugin enable /path/to/vault --id dataview

# List installed plugins

obsidian plugin list /path/to/vault

# Install a theme

obsidian theme install /path/to/vault --name "Minimal"

---

## Defuddle — Clean Web Extraction

Defuddle extracts clean Markdown from web pages, removing navigation, ads, and clutter.

### Install

npm install -g defuddle-cli

### Usage

# Extract clean markdown from a URL

defuddle https://example.com/article

# Save output to a file

defuddle https://example.com/article -o output.md

# Extract and save directly into your vault

defuddle https://example.com/article -o /path/to/vault/Clippings/article.md

# Include metadata as frontmatter

defuddle https://example.com/article --frontmatter

# Specify output format

defuddle https://example.com/article --format markdown

defuddle https://example.com/article --format text

### Programmatic Usage

import { Defuddle } from 'defuddle';

const result = await Defuddle.parse('https://example.com/article');

console.log(result.markdown);

console.log(result.title);

console.log(result.author);

console.log(result.date);

### Save Clippings to Vault

#!/bin/bash

# save-clip.sh — Save a URL as a clipping to Obsidian vault

URL="$1"

VAULT="/path/to/vault"

DATE=$(date +%Y-%m-%d)

defuddle "$URL" \

--frontmatter \

-o "$VAULT/Clippings/$DATE-clipping.md"

---

## Common Patterns

### Creating a Project Note

---

title: My Project

type: project

status: active

due: 2026-06-01

tags:

- work

- development

---

# My Project

Overview

Brief description here.

Tasks

Related Notes

Resources

![[attachments/diagram.png]]

### Creating a Base for Active Projects

# active-projects.base

view: board

groupBy: status

filter:

type: and

conditions:

- type: eq

field: type

value: project

- type: neq

field: status

value: archived

fields:

- title

- due

- priority

sort:

- field: due

order: asc

summary:

- field: title

type: count

### Script: Bulk Import Web Clippings

#!/bin/bash

# bulk-clip.sh — Import a list of URLs into Obsidian vault

VAULT="${OBSIDIAN_VAULT_PATH:-$HOME/vault}"

CLIPPINGS_DIR="$VAULT/Clippings"

mkdir -p "$CLIPPINGS_DIR"

while IFS= read -r url; do

filename=$(echo "$url" | sed 's|https\?://||;s|/|-|g' | cut -c1-60)

echo "Clipping: $url"

defuddle "$url" --frontmatter -o "$CLIPPINGS_DIR/${filename}.md"

done < urls.txt

---

## Troubleshooting

### Skills not loading in Claude Code

Ensure the repo is placed in the `/.claude` folder at the **root of your vault**, not in a subfolder:

vault/

.claude/

skills/

obsidian-markdown/

SKILL.md

...

### Skills not loading in OpenCode

Make sure you cloned the **full repo** (not just the `skills/` subfolder) into `~/.opencode/skills/`:

~/.opencode/skills/

obsidian-skills/ ← full repo root here

skills/

obsidian-markdown/

SKILL.md

Restart OpenCode after cloning — skills are auto-discovered on startup.

### Defuddle returns empty output

Some sites require JavaScript rendering. Use a headless browser flag if supported:

defuddle https://example.com --js

### Wikilinks not resolving

Wikilinks are case-sensitive and must match the note filename exactly. Check:
- Capitalization matches the file name
- Special characters are handled correctly
- The note exists in the vault (not just in a different vault)

### Base file not showing data

- Ensure the `.base` file is inside your Obsidian vault directory
- Check that referenced properties exist in your notes' frontmatter
- Validate YAML syntax in both the base file and note frontmatter

---

## Environment Variables

# Set your default vault path for CLI scripts

export OBSIDIAN_VAULT_PATH="/path/to/your/vault"

# Defuddle API key (if using cloud features)

export DEFUDDLE_API_KEY="your-key-here"

---

## Resources

- [Obsidian Help: Obsidian Flavored Markdown](https://help.obsidian.md/obsidian-flavored-markdown)
- [Obsidian Help: Bases Syntax](https://help.obsidian.md/bases/syntax)
- [JSON Canvas Spec](https://jsoncanvas.org/)
- [Defuddle CLI](https://github.com/kepano/defuddle-cli)
- [Agent Skills Specification](https://agentskills.io/specification)
- [obsidian-skills GitHub](https://github.com/kepano/obsidian-skills)