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

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

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