К основному содержанию
скилл CX Codex

obsidian · julianobarbosa — скилл для Claude Code: вольты, плагины, REST API

Учит агента работать с вольтом Obsidian: структура .obsidian/, плагины на TypeScript, ссылки obsidian:// и Local REST API для запросов к заметкам.

MIT 244 установок ★ 17 обновлён 2026-10-14

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add julianobarbosa/claude-code-skills --skill obsidian -a claude-code
Открыть на GitHub

Что делает obsidian

Скилл даёт агенту карту вольта: где лежат настройки в .obsidian/, как устроены app.json, community-plugins.json и папки плагинов, чем отличаются file и path в ссылках obsidian://. Дальше идёт разработка плагинов на TypeScript: шаблон с onload() и onunload(), регистрация команд и обработчиков событий, классы App, Vault, Workspace, MetadataCache.

Автоматизацию снаружи скилл раскладывает на три дороги: простые открытия и создание заметок через obsidian://, сложные вставки через Advanced URI, полный доступ через Local REST API. Для последнего нужен одноимённый плагин из Community Plugins и ключ, который вы прописываете в его настройках — без него curl с заголовком Authorization получит отказ. Сертификат там самоподписанный, поэтому в Python-примере стоит verify = False.

Эндпоинты закрывают список файлов, чтение и запись заметок, поиск, запуск команд и открытие файла в приложении. Плагин ставится в вольт, а не в систему, так что на каждой машине его включают заново.

Какие задачи решает

  • Разобрать чужой вольт: что лежит в .obsidian/ и какие плагины включены
  • Написать плагин с командой, которая правит текст в редакторе
  • Создать заметку из скрипта по ссылке obsidian://new
  • Настроить запросы к заметкам через Local REST API с ключом
  • Выбрать между URI-схемой, Advanced URI и REST API под задачу

Примеры запросов агенту

  • Покажи, что лежит в .obsidian/ вольта my-vault, и перечисли включённые плагины
  • Напиши плагин Obsidian с командой, которая вставляет строку в текущую заметку
  • Через Local REST API на https://127.0.0.1:27124 запиши текст в Notes/NewNote.md

Как установить obsidian

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/obsidian/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об obsidian

Как установить скилл obsidian в Claude Code?

Выполните npx skills add julianobarbosa/claude-code-skills --skill obsidian -a claude-code. Файл скилла появится по пути ~/.claude/skills/obsidian/SKILL.md.

Что делает скилл obsidian?

Даёт агенту инструкции по вольтам Obsidian: структура папок, разработка плагинов, схема obsidian:// и работа с Local REST API.

Что нужно для работы Local REST API?

Плагин Local REST API из Community Plugins и ключ, прописанный в его настройках. Сертификат самоподписанный, поэтому клиенту придётся отключить проверку.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Заметки, задачи и проекты» →

Сначала — obsidian от других авторов.

obsidian openclaw Подключает официальный obsidian CLI для чтения, поиска, создания и редактирования заметок в хранилище Obsidian. CX Codex +1 6 400установок obsidian Teknium (teknium1), Hermes Agent Читает, ищет, создаёт и редактирует заметки в хранилище Obsidian. CX Codex +1 503установок obsidian bitbonsai Маршрутизирует работу с хранилищем Obsidian между MCP-сервером, CLI приложения и git. Помогает безопасно переименовывать заметки, обновлять теги и делать бэкапы. CX Codex +1 1 700установок obsidian steipete Управляет локальным хранилищем Obsidian: ищет, читает и редактирует заметки. Запускается для задач с заметками, обратными ссылками, Bases и Canvas. CX Codex +1 104установок obsidian Delphine-L Помогает вести заметки, задачи и документацию проекта в Obsidian. При создании заметки он сначала запрашивает место сохранения. CX Codex +1 101установок obsidian-markdown AgriciDaniel Скилл obsidian-markdown объясняет, черновики и проверяет синтаксис Obsidian Flavored Markdown: свойства, wikilinks, вставки, callouts, теги, блоки, математику и Mermaid. CX Codex +1 593установок obsidian-cli kepano Скилл obsidian-cli для Claude Code управляет заметками и поиском в хранилище Obsidian через CLI. Также помогает разрабатывать и отлаживать плагины и темы. CX Codex +1 83 700установок Obsidian Automation Claude Office Skills Скилл Obsidian Automation для Claude Code и других агентов: создаёт заметки Obsidian по шаблонам, расставляет ссылки и разбирает граф связей в Markdown-хранилище. CX Codex +1 5 000установок obsidian-companion thoreinstein Скилл obsidian-companion подключает агент к хранилищу Obsidian: позволяет искать заметки, вести ежедневные записи и отвечать на вопросы по базе через локальный RAG. CX Codex +1 ★ 102звёзд репо obsidian-organizer Agents365-ai Скилл obsidian-organizer для Claude Code и Codex. Раскладывает заметки по папкам хранилища Obsidian и наводит порядок в структуре, когда входящие копятся в корне и нельзя ломать связи между файлами. CX Codex +1 1 900установок obsidian-notes-creator szeyu Скилл obsidian-notes-creator создаёт, дополняет и проверяет учебные заметки Obsidian по лекциям, учебникам и PDF-файлам. Форматирует конспекты с LaTeX-формулами, диаграммами Mermaid и подробными решениями задач. CX Codex +1 689установок

Из того же набора37

Весь набор →
markitdown Скилл-инструкция по Microsoft MarkItDown: превращает PDF, Word, Excel, картинки и ссылки в Markdown, готовый для контекста LLM. CX Codex +1 1 700установок obsidian-vault-management Скилл obsidian-vault-management для Claude Code управляет хранилищем Obsidian по структуре PARA, создаёт заметки, настраивает ежедневники и собирает запросы Dataview. Организует ведение базы знаний через терминал. CX Codex +1 315установок neovim Помогает ИИ-агенту настраивать модульную сборку Neovim на базе lazy.nvim, подключать LSP-серверы, настраивать отладчик DAP и оптимизировать старт. CX Codex +1 308установок argocd-advanced Скилл argocd-advanced для Claude Code разбирает продвинутые операции ArgoCD: ApplicationSet, автообновление образов и ввод кластера в GitOps-контур. CX Codex +1 231установок researching-web Скилл researching-web отправляет вопрос в Perplexity через MCP и возвращает разбор по теме: свежие релизы, сравнения технологий, принятые практики. CX Codex +1 200установок 1password Учит агента работать с 1Password: доставать секреты через op, подставлять их в окружение и отдавать в Kubernetes. CX Codex +1 172установок mkdocs Помогает создать и настроить сайт документации на MkDocs из Markdown-файлов. Помогает собрать, локально просматривать и публиковать сайт. CX Codex +1 157установок loki Скилл помогает настраивать Grafana Loki: выбирать режим развёртывания и хранилище, задавать параметры и писать запросы LogQL. Пригодится при внедрении Loki и разборе проблем. CX Codex +1 148установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой