Trending-skills obsidian-skills-agent

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

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

Claude Code (Manual)

Copy the repo contents into a

/.claude

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

Codex CLI (Manual)

Copy the

skills/

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

obsidian-markdown

skills/obsidian-markdown/SKILL.md

obsidian-bases

skills/obsidian-bases/SKILL.md

.base

json-canvas

skills/json-canvas/SKILL.md

.canvas

obsidian-cli

skills/obsidian-cli/SKILL.md

defuddle

skills/defuddle/SKILL.md

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

- List item with block ID ^list-block

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

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

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"

"2"

"3"

"4"

"5"

"6"

"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

- [ ] Task one
- [ ] Task two
- [x] Completed task

## Related Notes

- [[Research/Background]]
- [[Meetings/Kickoff Meeting]]

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

vault/
  .claude/
    skills/
      obsidian-markdown/
        SKILL.md
      ...

Skills not loading in OpenCode

Make sure you cloned the full repo (not just the

skills/

~/.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
• Obsidian Help: Bases Syntax
• JSON Canvas Spec
• Defuddle CLI
• Agent Skills Specification
• obsidian-skills GitHub