Skip to main content
skill CX Codex

obsidian · julianobarbosa — Claude Code skill: vaults, plugins, REST API

Teaches the agent how an Obsidian vault is laid out, how to write plugins for it, and how to drive notes from outside through obsidian:// links or the Local REST API.

MIT 244 installs ★ 17 updated 2026-10-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add julianobarbosa/claude-code-skills --skill obsidian -a claude-code
Open on GitHub

What obsidian does

The skill hands the agent a working map of a vault: .obsidian/ with app.json, community-plugins.json, hotkeys and per-plugin data folders, plus the obsidian:// parameters (vault, file, path, name, content, query). Plugin work is covered too, from a main.ts entry point and manifest.json to commands, editor callbacks and the App, Vault, Workspace and MetadataCache classes.

Outside automation splits three ways, and the skill helps you choose: the native URI scheme for opening and creating notes, the Advanced URI plugin when you need to append or fire a command, the Local REST API plugin for full HTTP access. That last route needs the community plugin enabled and an API key set in its settings; a request without the bearer token is rejected. Its certificate is self-signed, which is why the Python snippet turns verification off.

Endpoints cover listing, reading, writing and deleting files, search, running a command and opening a note in the app. Everything sits inside the vault, so each machine needs the plugin enabled on its own.

What it helps with

  • Map an unfamiliar vault, including .obsidian/ settings and enabled plugins
  • Scaffold a plugin that registers a command and an editor callback
  • Create a note from a script with an obsidian://new link
  • Query and update notes over the Local REST API with a bearer token
  • Decide between the URI scheme, Advanced URI and the REST plugin

Example prompts for the agent

  • Walk me through the .obsidian/ folder of my-vault and list the enabled plugins
  • Write an Obsidian plugin whose command inserts a line into the open note
  • Use the Local REST API at https://127.0.0.1:27124 to write Notes/NewNote.md

How to install obsidian

1Skills CLI (Vercel)

npx skills add julianobarbosa/claude-code-skills --skill obsidian -a claude-code

2Manually: put the files in place

~/.claude/skills/obsidian/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/obsidian/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about obsidian

How do I install the obsidian skill in Claude Code?

Run npx skills add julianobarbosa/claude-code-skills --skill obsidian -a claude-code. The skill file lands at ~/.claude/skills/obsidian/SKILL.md.

What does the obsidian skill do?

It briefs the agent on vault layout, plugin development with the Obsidian API, obsidian:// links and the Local REST API.

Do I need the Local REST API plugin for this?

Only for HTTP access to notes. Install it from Community Plugins, enable it and put the API key in its settings; the certificate is self-signed, so clients must skip verification.

Source text

SKILL.md · MIT
---
name: obsidian
description: >-
  Guide for implementing Obsidian knowledge management - vault operations,
  plugin development, URI scheme automation, markdown extensions, and Local
  REST API integration. Use when working with Obsidian vaults, creating
  plugins, automating note workflows, querying notes via API, or implementing
  knowledge graph features.
---

# Obsidian

## Overview

This skill provides comprehensive guidance for working with Obsidian,
a powerful knowledge management and note-taking application.
It covers vault structure, the Obsidian API for plugin development,
URI scheme automation, markdown extensions, and integration with
external tools via the Local REST API.

## Quick Reference

### Vault Structure

```text
my-vault/
├── .obsidian/              # Configuration folder
│   ├── app.json            # App settings
│   ├── appearance.json     # Theme settings
│   ├── community-plugins.json  # Installed plugins list
│   ├── core-plugins.json   # Core plugin toggles
│   ├── hotkeys.json        # Custom keybindings
│   ├── plugins/            # Plugin data folders
│   │   └── <plugin-id>/
│   │       ├── main.js     # Compiled plugin code
│   │       ├── manifest.json
│   │       └── data.json   # Plugin settings
│   └── workspace.json      # Layout state
├── Notes/                  # User notes (any structure)
├── Attachments/            # Images, PDFs, etc.
└── Templates/              # Template files
```

### Obsidian URI Scheme

Native Obsidian supports `obsidian://` protocol for automation:

```bash
# Open a vault
obsidian://open?vault=MyVault

# Open a specific file
obsidian://open?vault=MyVault&file=Notes/MyNote

# Create a new note
obsidian://new?vault=MyVault&name=NewNote&content=Hello

# Search the vault
obsidian://search?vault=MyVault&query=keyword

# Open daily note
obsidian://daily?vault=MyVault
```

### URI Parameters

| Parameter | Description |
|-----------|-------------|
| `vault` | Vault name (required) |
| `file` | File path without `.md` extension |
| `path` | Full file path including folders |
| `name` | Note name for creation |
| `content` | Content to insert |
| `query` | Search query |
| `heading` | Navigate to heading |
| `block` | Navigate to block reference |

## Workflow Decision Tree

```text
What do you need to do?
├── Automate Obsidian from external tools?
│   ├── Simple open/create operations?
│   │   └── Use: Native obsidian:// URI scheme
│   ├── Complex automation (append, prepend, commands)?
│   │   └── Use: Advanced URI plugin
│   └── Full programmatic access?
│       └── Use: Local REST API plugin
├── Build a plugin for Obsidian?
│   └── See: Plugin Development section
├── Work with vault files directly?
│   └── Use: obsidian-cli or direct file operations
├── Extend markdown syntax?
│   └── See: Markdown Extensions section
└── Query notes and metadata?
    └── Use: Local REST API or Dataview plugin
```

## Plugin Development

### Plugin Structure

```text
my-plugin/
├── main.ts           # Plugin entry point
├── manifest.json     # Plugin metadata
├── package.json      # npm dependencies
├── styles.css        # Optional styles
├── tsconfig.json     # TypeScript config
└── esbuild.config.mjs # Build config
```

### manifest.json

```json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "minAppVersion": "1.0.0",
  "description": "A sample plugin for Obsidian",
  "author": "Your Name",
  "authorUrl": "https://github.com/username",
  "isDesktopOnly": false
}
```

### Basic Plugin Template

```typescript
import { Plugin, Notice, MarkdownView } from 'obsidian';

export default class MyPlugin extends Plugin {
  async onload() {
    console.log('Loading plugin');

    // Register a command
    this.addCommand({
      id: 'my-command',
      name: 'My Command',
      callback: () => {
        new Notice('Hello from my plugin!');
      }
    });

    // Register editor command
    this.addCommand({
      id: 'my-editor-command',
      name: 'Insert Text',
      editorCallback: (editor, view: MarkdownView) => {
        editor.replaceSelection('Inserted text');
      }
    });

    // Register event listener
    this.registerEvent(
      this.app.workspace.on('file-open', (file) => {
        if (file) {
          console.log('Opened:', file.path);
        }
      })
    );
  }

  onunload() {
    console.log('Unloading plugin');
  }
}
```

### Core API Classes

| Class | Purpose | Access |
|-------|---------|--------|
| `App` | Central application instance | `this.app` |
| `Vault` | File system operations | `this.app.vault` |
| `Workspace` | Pane and layout management | `this.app.workspace` |
| `MetadataCache` | File metadata indexing | `this.app.metadataCache` |
| `FileManager` | User-safe file operations | `this.app.fileManager` |

### Plugin Lifecycle

```typescript
// onload() - Called when plugin is enabled
async onload() {
  // Initialize UI components
  // Register event handlers
  // Set up commands
  // Load settings
}

// onunload() - Called when plugin is disabled
onunload() {
  // Cleanup is mostly automatic
  // Custom cleanup for external resources
}
```

## Local REST API

The Local REST API plugin provides HTTP endpoints to interact with Obsidian programmatically.

### Installation

1. Install "Local REST API" from Community Plugins
2. Enable the plugin
3. Configure API key in settings
4. Default endpoint: `https://127.0.0.1:27124`

### Authentication

```bash
# Using API key header
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://127.0.0.1:27124/vault/
```

### Common Endpoints

```bash
# List all files
GET /vault/

# Get file content
GET /vault/{path-to-file}

# Create/Update file
PUT /vault/{path-to-file}
Content-Type: text/markdown
Body: File content here

# Delete file
DELETE /vault/{path-to-file}

# Search vault
POST /search/simple/
Content-Type: application/json
Body: {"query": "search term"}

# Execute command
POST /commands/{command-id}

# Get active file
GET /active/

# Open file in Obsidian
POST /open/{path-to-file}
```

### Python Example

```python
import requests

class ObsidianAPI:
    def __init__(self, api_key, base_url="https://127.0.0.1:27124"):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
        self.session = requests.Session()
        self.session.verify = False  # Self-signed cert

    def list_files(self, path=""):
        response = self.session.get(
            f"{self.base_url}/vault/{path}",
            headers=self.headers
        )
        return response.json()

    def read_file(self, path):
        response = self.session.get(
            f"{self.base_url}/vault/{path}",
            headers=self.headers
        )
        return response.text

    def write_file(self, path, content):
        response = self.session.put(
            f"{self.base_url}/vault/{path}",
            headers={**self.headers, "Content-Type": "text/markdown"},
            data=content.encode('utf-8')
        )
        return response.status_code == 204

    def search(self, query):
        response = self.session.post(
            f"{self.base_url}/search/simple/",
            headers=self.headers,
            json={"query": query}
        )
        return response.json()
```

## Markdown Extensions

Obsidian extends standard Markdown with special syntax:

### Internal Links (Wikilinks)

```markdown
[[Note Name]]                    # Link to note
[[Note Name|Display Text]]       # Link with alias
[[Note Name#Heading]]            # Link to heading
[[Note Name#^block-id]]          # Link to block
[[Note Name#^block-id|alias]]    # Block link with alias
```

### Embeds (Transclusion)

```markdown
![[Note Name]]                   # Embed entire note
![[Note Name#Heading]]           # Embed section
![[Note Name#^block-id]]         # Embed block
![[image.png]]                   # Embed image
![[image.png|300]]               # Embed with width
![[image.png|300x200]]           # Embed with dimensions
![[audio.mp3]]                   # Embed audio
![[video.mp4]]                   # Embed video
![[document.pdf]]                # Embed PDF
```

### Callouts

```markdown
> [!note] Title
> Content here

> [!warning] Caution
> Important warning message

> [!tip]+ Expandable (default open)
> Click to collapse

> [!info]- Collapsed (default closed)
> Click to expand

# Available types:
# note, abstract, summary, tldr, info, todo, tip, hint,
# important, success, check, done, question, help, faq,
# warning, caution, attention, failure, fail, missing,
# danger, error, bug, example, quote, cite
```

### Block References

```markdown
This is a paragraph. ^block-id

# Reference this block from another note:
[[Note#^block-id]]
```

### Tags

```markdown
#tag
#nested/tag
#tag-with-dashes
```

### Frontmatter (YAML)

```markdown
---
title: My Note
date: 2024-01-15
tags:
  - tag1
  - tag2
aliases:
  - alternate name
cssclass: custom-class
---

# Note content starts here
```

### Comments

```markdown
%%This is a comment that won't render%%

%%
Multi-line
comment
%%
```

### Math (LaTeX)

```markdown
Inline: $E = mc^2$

Block:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$
```

### Mermaid Diagrams

````markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
```
````

## CLI Tools

### obsidian-cli (Yakitrak)

```bash
# Install
go install github.com/Yakitrak/obsidian-cli@latest

# Commands
obsidian-cli open "Note Name"         # Open note
obsidian-cli search "query"           # Fuzzy search
obsidian-cli create "New Note"        # Create note
obsidian-cli daily                    # Open daily note
obsidian-cli list                     # List notes
```

### obsidian-cli (Python)

```bash
# Install
pip install obsidian-cli

# Commands
obs vault list                        # List vaults
obs vault create <name>               # Create vault
obs note search <query>               # Search notes
obs settings export                   # Export settings
```

## Best Practices

1. **Use separate dev vault**: Never develop plugins in your main vault
2. **Hot reload plugin**: Install for faster development iteration
3. **Use registerEvent()**: Ensures proper cleanup on unload
4. **Prefer UIDs over paths**: File paths can change; use unique identifiers
5. **Handle async properly**: Use await for vault operations
6. **Test with Obsidian sandbox**: Use BRAT plugin for beta testing
7. **Follow manifest conventions**: Keep id matching folder name
8. **Version carefully**: Update versions.json for compatibility

## Troubleshooting

### Plugin Not Loading

```bash
# Check console for errors
Ctrl+Shift+I (or Cmd+Option+I on Mac)

# Verify manifest.json is valid JSON
jq . manifest.json

# Check minAppVersion compatibility
# Ensure main.js exists in plugin folder
```

### URI Not Working

```bash
# URL encode special characters
# Spaces: %20
# Slashes: %2F
# Ampersands: %26

# Test with simple vault name first
obsidian://open?vault=test
```

### REST API Connection Failed

```bash
# Verify plugin is enabled
# Check API key is correct
# Confirm HTTPS and self-signed cert handling
# Default port: 27124
```

## Resources

### References

- `references/uri-scheme.md` - Complete URI scheme documentation
- `references/plugin-development.md` - Plugin development guide
- `references/vault-structure.md` - Vault and config structure
- `references/markdown-extensions.md` - Obsidian markdown syntax
- `references/api-reference.md` - TypeScript API reference

### Scripts

- `scripts/obsidian-vault.sh` - Vault management utilities
- `scripts/obsidian-api.py` - Local REST API Python client

### External Documentation

- [Obsidian Developer Documentation](https://docs.obsidian.md/)
- [Obsidian API Types](https://github.com/obsidianmd/obsidian-api)
- [Sample Plugin Template](https://github.com/obsidianmd/obsidian-sample-plugin)
- [Local REST API Plugin](https://github.com/coddingtonbear/obsidian-local-rest-api)
- [Advanced URI Plugin](https://vinzent03.github.io/obsidian-advanced-uri/)
- [Obsidian Help](https://help.obsidian.md/)

---

## Absorbed sub-skill (post-consolidation)

This skill now subsumes the former `obsidian-master` skill (the "unified orchestration" umbrella). Its content is preserved as deep reference:

| Subject | Path |
|---------|------|
| Original orchestration SKILL.md (multi-step vault workflows) | `References/master.md` |
| Master skill's reference docs | `References/master-reference/` |
| Master skill's workflows | `References/master-workflows/` |
| Master skill's tools | `References/master-tools/` |

The former `obsidian-second-brain` skill has been renamed to **`obsidian-claude-integration`** to reflect what it actually is: integration patterns for Claude Code + Obsidian, not a generic "second brain" concept.

Narrow siblings still apply:
- **`obsidian-markdown`** — syntax only (wikilinks, embeds, callouts, frontmatter, tags, LaTeX, Mermaid).
- **`obsidian-bases`** — Bases (.base YAML, table views, filters, formulas) only.
- **`obsidian-nvim`** — the `obsidian.nvim` Neovim plugin only.
- **`obsidian-vault-management`** — CRUD on vault contents (notes, templates, Dataview).
- **`obsidian-claude-integration`** — Claude Code ↔ Obsidian integration patterns.

---

## Gotchas

- **Wikilink `[[Note]]` resolution picks the first alphabetical match in the vault when duplicates exist** — silently. Two notes named "Index" in different folders create an invisible ambiguity.
- **`obsidian://` URI scheme requires the vault to be open in the desktop app** — headless contexts (CI, Claude Code without Obsidian running) silently no-op.
- **Local REST API plugin must be enabled separately** from the API key — default port 27124, but the plugin must be running for any HTTP request to land.
- **Markdown footnotes (`[^1]`) require a blank line before the definition** — without the blank line, Obsidian renders them as plain text, no error.
- **Vault path with spaces/special chars: most plugins handle it; some shell-integration plugins don't.** Test scripted invocations explicitly.

© julianobarbosa · MIT · julianobarbosa/claude-code-skills

Similar skills

All skills for Notes, tasks and projects →

obsidian by other authors comes first.

obsidian openclaw Connects the official obsidian CLI so agents can read, search, create and edit notes inside an Obsidian vault. CX Codex +1 6,400installs obsidian Teknium (teknium1), Hermes Agent A skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that reads, searches, creates, and edits notes in an Obsidian vault. CX Codex +1 503installs obsidian bitbonsai Routes Obsidian vault tasks between MCP tools, app CLI actions, and git sync. It handles note edits, backlink repairs on renames, and automated repository backups. CX Codex +1 1,700installs obsidian steipete A skill for Claude Code searches, reads, and edits local Obsidian vaults. It handles requests involving notes, backlinks, Bases, and Canvas. CX Codex +1 104installs obsidian Delphine-L This Claude Code skill manages project notes, tasks, and documentation in Obsidian. Before creating a note, it asks where the file should go. CX Codex +1 101installs obsidian-markdown AgriciDaniel The obsidian-markdown skill explains, drafts and validates Obsidian Flavored Markdown: properties, wikilinks, embeds, callouts, tags, block references, math and Mermaid. CX Codex +1 593installs obsidian-cli kepano This Claude Code skill uses the Obsidian CLI to search and edit vault content. It also assists with plugin and theme development and debugging. CX Codex +1 83,700installs Obsidian Automation Claude Office Skills Obsidian Automation — a skill for Obsidian knowledge bases: creates notes from templates, adds internal links and reads the link graph. Useful if you keep a Markdown wiki. CX Codex +1 5,000installs obsidian-companion thoreinstein obsidian-companion connects your assistant to an Obsidian vault to edit files, inspect broken wikilinks, and run queries using local RAG. CX Codex +1 ★ 102repo stars obsidian-organizer Agents365-ai obsidian-organizer files notes into the right Obsidian vault folders and audits structure. It helps when an inbox grows messy and manual sorting breaks internal links. CX Codex +1 1,900installs obsidian-notes-creator szeyu obsidian-notes-creator is a Claude Code skill for creating, improving, and auditing Obsidian study notes from lectures, textbooks, and PDFs, with LaTeX, Mermaid, and worked solutions. CX Codex +1 689installs

From the same set37

The whole set →
markitdown Teaches the agent to use Microsoft MarkItDown, turning PDFs, Office files, images and URLs into Markdown for LLM context. CX Codex +1 1,700installs obsidian-vault-management obsidian-vault-management manages Obsidian vaults using PARA folders, creates structured notes, and writes Dataview queries. Helpful when maintaining personal knowledge bases with an agent. CX Codex +1 315installs neovim Guides AI coding agents through configuring a modular, performance-focused Neovim setup built on lazy.nvim, LSP, and DAP debugging. CX Codex +1 308installs argocd-advanced argocd-advanced covers the automation side of ArgoCD: ApplicationSet generators, automatic image updates and bringing a new cluster into a GitOps setup. Reach for it when sync and diff commands are not enough. CX Codex +1 231installs researching-web researching-web — a skill that routes your question to Perplexity over MCP and brings back a written answer: current releases, technology comparisons, accepted practice. CX Codex +1 200installs 1password Gives the agent a working map of 1Password: pull a secret with op, feed it to your app, wire vaults into Kubernetes. CX Codex +1 172installs mkdocs This skill guides an agent through building a MkDocs documentation site from Markdown. Use it to configure pages, preview a site, or prepare a deployment. CX Codex +1 157installs loki This skill guides Grafana Loki configuration, from deployment modes and storage backends to LogQL queries. Use it while setting up Loki or investigating its configuration. CX Codex +1 148installs

Project sponsors

Companies that keep this analytics open