# Obsidian

> Работа с хранилищем Obsidian (filesystem-first — читает и пишет Markdown напрямую): заметки и клиппинги (URL, статьи, сниппеты), проектные задачи, синтез исследований, решения/ADR, дневник работы, брифы, периодические ревью, анализ графа тегов и ссылок. Используй когда пользователь просит сохранить заметку/клиппинг, добавить задачу, разобрать структуру vault, синтезировать источники, записать решение, подвести итоги дня, сделать бриф проекта, провести ревью или навести порядок в тегах и связях Obsidian.

- Skill: `goldenprofile/obsidian` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add goldenprofile/obsidian`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goldenprofile/obsidian/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: goldenprofile (https://skillmd.com/u/goldenprofile)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goldenprofile/obsidian

---


# Obsidian Vault

Единый навык для всех операций с хранилищем Obsidian: базовое управление заметками,
приём клиппингов, проектные задачи, синтез исследований, записи решений (ADR),
дневник, проектные брифы, периодические ревью и анализ графа тегов/ссылок. Все
рабочие процессы — filesystem-first: навык работает с Markdown-файлами vault напрямую.

## Инструменты

Навык работает с файлами vault штатными инструментами ассистента. Имена инструментов
зависят от харнесса (Claude Code, pi, Codex), поэтому ниже — возможности, а не имена
конкретного харнесса:

| Возможность | Инструмент |
|-------------|------------|
| Чтение файлов | `Read` / `read` |
| Поиск по имени/маске | `Glob` / `glob`, `find`, `ls` |
| Поиск по содержимому | `Grep` / `grep` (regex) |
| Создать/перезаписать заметку | `Write` / `write` |
| Точечная правка | `Edit` / `edit` |
| Терминал (git, дата, curl, скрипты) | `Bash` (POSIX) или `PowerShell` |
| Загрузка URL | `WebFetch`, если есть; иначе `curl -sL --max-time 30` через терминал |
| Параллельная обработка пачки | субагенты, если харнесс умеет; иначе последовательно |

Полноценная браузерная автоматизация (JS-heavy SPA, скриншоты, PDF в браузере) —
вне ядра навыка. Для неё используй Playwright MCP или Claude-in-Chrome, если
они подключены.

Навык ведёт обычный Obsidian-flavored markdown + wikilinks. Авторство
Obsidian-специфичных форматов — Bases (`.base`) и Canvas (`.canvas`) — вне его ядра.
Если нужно, чтобы агент писал валидные `.base`-вьюхи или `.canvas`-доски, подключи
официальные [`kepano/obsidian-skills`](https://github.com/kepano/obsidian-skills)
(скиллы `obsidian-bases` и `json-canvas`, открытая спека Agent Skills; от CEO Obsidian).

## Путь к хранилищу

Определи корень vault один раз, дальше передавай инструментам абсолютные пути.
Порядок разрешения:

1. Переменная окружения `OBSIDIAN_VAULT_PATH`, если задана.
2. Путь, который явно указал пользователь.
3. Автоопределение: `Glob` по `**/.obsidian` — эта папка лежит в корне любого vault.

Никогда не передавай инструментам строку `$OBSIDIAN_VAULT_PATH` буквально — сначала
разверни её в реальный путь.

## Структура папок (пример)

Навык не требует жёсткой структуры и подстраивается под ту, что есть в vault.
Типовая PARA-подобная раскладка (это роли, а не обязательные имена):

| Роль | Пример пути | Что хранит |
|------|-------------|------------|
| Inbox | `inbox/` | Клиппинги, необработанное |
| Projects | `projects/<Project>/` | Задачи, ADR, проектные документы |
| Logs | `logs/` | Дневник работы |
| Maps | `maps/` | MOC, дашборды |
| Attachments | `attachments/` | Медиа |

Если в vault другие имена (например, нумерованные `1-INBOX/`, `2-PROJECTS/`,
`9-META/ATTACHMENTS/`) — спроецируй эти роли на них.

## Разделы

| Раздел | Reference | Когда использовать |
|--------|-----------|--------------------|
| **Базовые операции** | ниже | Чтение, поиск, создание, правка заметок |
| **Клиппинги** | `references/obsidian-clippings.md` | Приём URL/статей/пересланного контента в vault |
| **Задачи** | `references/obsidian-tasks.md` | Проектные задачи со статусами |
| **Vault Zen** | `references/vault-zen.md` | Анализ структуры, предложения по организации |
| **Синтез исследований** | `references/research-synthesis.md` | Сведение нескольких источников в одну заметку |
| **Записи решений** | `references/decision-records.md` | Фиксация архитектурных/технических решений (ADR) |
| **Дневник** | `references/daily-log.md` | Ретроспектива: что сделано, решения, блокеры |
| **Бриф проекта** | `references/project-brief.md` | Снимок статуса проекта из данных vault |
| **Режим ревью** | `references/review-mode.md` | Периодическое ревью: протухшие задачи, inbox, мёртвые проекты |
| **Граф тегов и ссылок** | `references/tag-link-graph.md` | Здоровье тегов, орфаны, MOC |

---

## Базовые операции

### Прочитать заметку
`Read` с абсолютным путём — даёт номера строк и пагинацию.

### Список заметок
`Glob` с паттерном `**/*.md` под путём vault.

### Поиск
- **По имени файла**: `Glob` (`**/*query*.md`)
- **По содержимому**: `Grep` (regex, `glob: "*.md"`, `path` = vault)

### Создать заметку
`Write` с абсолютным путём и полным Markdown-содержимым.

### Дописать в заметку
- Прочитай заметку `Read`
- `Edit` для якорной вставки (после заголовка, перед известным блоком)
- `Write`, когда переписать целиком проще, чем городить хрупкий патч

### Точечные правки
`Edit`, когда текущее содержимое даёт стабильный контекст для замены.

### Wikilinks
Obsidian связывает заметки через `[[Имя заметки]]`. При создании заметок используй
их для связи с релевантным контентом.

---

## Дата (общее правило для всех разделов)

Многие заметки именуются и помечаются датой. **Перед записью любого файла бери
сегодняшнюю реальную дату из контекста сессии** (харнесс сообщает текущую дату).
Не переиспользуй дату из предыдущей заметки и не угадывай год — это типовая ошибка.
При необходимости получить дату в терминале: `date +%F` (bash) или
`Get-Date -Format yyyy-MM-dd` (PowerShell).

---

## Неинтерактивный режим

Навык может исполняться headless: раннер запускает агента с задачей текстом,
диалоги недоступны. Правила:

- Не задавай вопросов. Выбирай безопасный дефолт: архив вместо удаления,
  новая заметка вместо правки дубликата, сохранение исходной формулировки.
- Каждое решение фиксируй в итоговом отчёте: что решил, какие были
  альтернативы, что пользователю стоит проверить.
- Деструктивные действия (удаление, перезапись) в headless запрещены —
  заменяй архивированием в зону архива vault.
- Фазные работы веди батчами с отчётом после каждого и продолжай без ожидания.

---

## Большие материалы

Документ больше ~30 КБ или папка больше ~100 файлов не читаются залпом:

- Сначала оглавление и структура (grep по заголовкам, ls), затем целевые
  секции точечным чтением.
- Разбор «по пунктам» (ROADMAP, бэклог) раскладывай на заметки/задачи частями:
  пункт → заметка, а не один гигантский ответ.
- Если материала больше, чем помещается в контекст, обработай приоритетные
  разделы и явно перечисли в отчёте, что осталось непрочитанным.

---

## Шаблоны

- `templates/clipping.md` — клиппинг с YAML-плейсхолдерами
- `templates/task.md` — задача со статусом/приоритетом

## Скрипты

- `scripts/html2md.py` — конвертер HTML→Markdown (только stdlib, без внешних
  зависимостей; `markdownify` подхватывается автоматически, если установлен). Для
  качественной конвертации статей/гайдов. Запуск через `Bash`:
  `python scripts/html2md.py page.html out.md --title "..." --tags "t1,t2"`.
  См. `references/obsidian-clippings.md` → «Quality HTML→Markdown conversion».

## Быстрая дизамбигуация

- **«Сохрани» / «Save this»** → клиппинг → `references/obsidian-clippings.md`
- **«Добавь задачу» / «Task»** → проектная задача → `references/obsidian-tasks.md`
- **«task <проект>: …» / «Task: …»** → зарегистрировать проектную задачу →
  `references/obsidian-tasks.md`. Работу, описанную в задаче, не выполнять.
- **«Аудит» / «Структура» / «Дзен» / «Разобрать папку»** → организация vault → `references/vault-zen.md`
- **«Сравни» / «Синтезируй» / «Что известно про X»** → синтез → `references/research-synthesis.md`
- **«Запиши решение» / «ADR» / «Почему выбрали»** → решение → `references/decision-records.md`
- **«Лог дня» / «Что сделали» / «Итоги»** → дневник → `references/daily-log.md`
- **«Контекст по проекту» / «Бриф» / «Статус проекта»** → бриф → `references/project-brief.md`
- **«Ревью» / «Что зависло» / «Почистить inbox»** → ревью → `references/review-mode.md`
- **«Карта знаний» / «Orphan» / «MOC» / «Связи» / «Теги в хаосе»** → граф → `references/tag-link-graph.md`
- **Обычная заметка** → базовые операции выше