obsidian-vault

name	obsidian-vault
description	Используй, когда нужно читать, искать, создавать, редактировать, организовывать или поддерживать заметки в Obsidian vault через файловые инструменты.
version	1.0.0
author	Hermes Agent
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["obsidian","notes","knowledge-management","markdown","vaults"],"related_skills":[]}}

Obsidian Vault

Обзор

Используй этот скилл для filesystem-first работы с Obsidian vault: читать заметки, выводить список файлов, искать по заметкам, создавать новые заметки, добавлять контент в существующие, организовывать папки, переносить или переименовывать заметки, создавать MOC/index notes, поддерживать теги и добавлять wikilinks.

Цель — вести себя как аккуратный хранитель базы знаний, а не как генератор текста, который разбрасывает заметки куда попало. Сохраняй существующую структуру пользователя, если он явно не попросил реорганизацию.

Когда использовать

Используй этот скилл, когда пользователь просит:

• прочитать, найти, суммаризировать или изучить заметки в Obsidian vault;
• создать или обновить Markdown-заметки;
• добавить в существующие заметки материалы встречи, идеи, ресёрч, summary или задачи;
• организовать папки, переименовать заметки или создать index/MOC notes;
• добавить или почистить Obsidian wikilinks и теги;
• создать или наполнить demo/test vault;
• проверить graph hygiene, unresolved links или структуру папок.

Не используй этот скилл для:

• обычного Markdown-текста, если речь не про vault;
• web research, если финальный артефакт не нужно сохранить в Obsidian vault;
• редактирования binary attachments, изображений, PDF или canvas-файлов, кроме случаев, когда их нужно сослать из Markdown-заметки.

Определение пути к vault

Перед вызовом файловых инструментов всегда определи путь к vault.

Предпочтительная конвенция:

OBSIDIAN_VAULT_PATH="/absolute/path/to/Obsidian Vault"

Переменная может быть задана в shell environment, project .env или agent-specific environment file. Если она не задана, используй fallback только если такая папка существует:

~/Documents/Obsidian Vault

Если нет ни environment variable, ни fallback-папки, спроси пользователя путь к vault перед изменением файлов.

Важные правила:

• File tools обычно не разворачивают shell variables. Не передавай пути вроде $OBSIDIAN_VAULT_PATH/Note.md в read_file, write_file, patch или search_files.
• Сначала получи конкретный абсолютный путь, потом передавай именно его в file tools.
• Пути к vault часто содержат пробелы. Для операций с заметками предпочитай file tools вместо shell-команд, чтобы не ошибиться с quoting.
• Если shell нужен, чтобы определить OBSIDIAN_VAULT_PATH, используй terminal только для discovery, а затем вернись к file tools.

Предпочтения по инструментам

Для работы с vault предпочитай структурированные file tools:

Задача	Предпочтительный tool	Избегать
Прочитать заметку	read_file	cat, less, editor UIs
Показать список заметок	search_files(target="files")	find, ls
Искать по содержимому	search_files(target="content")	grep, rg, если file tool доступен
Создать заметку	write_file	shell heredocs, цепочки echo
Точечная правка	patch	sed, ручные shell-rewrites
Проверить структуру	terminal с маленьким скриптом допустим	ручные догадки

Используй shell-команды только для того, что действительно требует shell behavior: запуск verification script, проверка environment variables, git или массовое перемещение файлов после понятного плана.

Чтение заметок

Используй read_file с абсолютным путём к заметке. Он даёт line numbers и pagination, что делает будущие patch-правки безопаснее.

Если пользователь дал неполное название:

1. Сначала ищи по именам файлов через search_files(target="files", pattern="*partial*.md").
2. Если filename не найден, ищи по содержимому через search_files(target="content", file_glob="*.md").
3. Если найдено несколько похожих заметок, выбери наиболее семантически релевантную или спроси пользователя только если ошибка может привести к рискованной правке.

Список заметок

Используй search_files с target: "files" и абсолютным путём к vault.

Примеры:

• все Markdown-заметки: pattern *.md внутри vault;
• одна папка: search под абсолютным путём этой папки;
• вероятные index notes: patterns вроде *MOC*.md, *Index*.md или folder-specific names.

Поиск по содержимому заметок

Используй search_files с target: "content".

Хорошие defaults:

• добавляй file_glob: "*.md", когда ищешь по заметкам;
• сначала используй конкретные термины из запроса пользователя;
• если первый поиск пустой, попробуй более широкие синонимы, прежде чем делать вывод, что в vault нет информации.

Когда сообщаешь результаты поиска, дай достаточно контекста, чтобы пользователь узнал заметку, но не выгружай большие тела заметок без просьбы.

Создание заметок

Используй write_file с полным Markdown-контентом и абсолютным путём внутри vault.

Перед созданием заметки:

1. Определи destination folder.
2. Проверь, нет ли уже заметки с таким же или очень похожим названием.
3. Используй человекочитаемый filename. Не создавай generic timestamp-only titles, если vault явно не использует такую конвенцию.
4. Сохраняй naming style пользователя, если его видно по соседним заметкам.

Рекомендуемая форма заметки:

---
tags: [topic/example]
status: draft
created: YYYY-MM-DD
---

# Clear Note Title

## Summary
Короткое summary или назначение заметки.

## Notes
Основной контент.

## Links
- Related: [[Existing Related Note]]

Используй frontmatter только если это подходит стилю vault. Если соседние заметки не используют frontmatter, не вводи его без необходимости.

Добавление в существующие заметки

Предпочитай workflow через file tools:

1. Прочитай target note через read_file.
2. Найди стабильный anchor: существующий heading, trailing section или точный TODO placeholder.
3. Используй patch для anchored append, когда это возможно.
4. Используй write_file, если переписать всю заметку понятнее и безопаснее, чем строить хрупкий patch.

Для простого append без стабильного контекста shell append допустим, но только после проверки точного абсолютного пути и shell quoting.

Если добавляешь dated entries, следуй существующему date format в vault. Если конвенции нет, используй ISO dates: YYYY-MM-DD.

Точечные правки

Используй patch для сфокусированных изменений, когда текущий контент даёт стабильный контекст.

Хорошие anchors для patch:

• точный heading и несколько следующих строк;
• конкретный bullet, который нужно расширить;
• TODO placeholder, который нужно заменить;
• существующее frontmatter field.

Избегай broad replace-all edits, если пользователь явно не попросил bulk cleanup и ты не проверил, что pattern безопасен.

Wikilinks

Obsidian связывает заметки через синтаксис [[Note Name]].

Правила:

• Добавляй wikilinks только когда они отражают реальную смысловую связь.
• Предпочитай ссылки на уже существующие заметки.
• Избегай иллюстративных fake links вроде [[Example Note]]: они создают unresolved nodes и загрязняют graph.
• Если создаёшь новую заметку и линкуешь её из другой, проверь, что обе стороны связи имеют смысл.
• Используй aliases только когда это полезно: [[Long Canonical Note Title|short label]].
• Не превращай каждое существительное в wikilink. Линкуй важные concepts, projects, people, sources и hubs.

Перед массовым добавлением links поищи существующие filenames, чтобы найти canonical note names.

Теги

Используй теги сдержанно и последовательно.

Правила:

• Предпочитай существующие tag namespaces, если они видны: #project/name, #topic/ai или frontmatter tags: [...].
• Добавляй теги только когда они улучшают retrieval или graph filtering.
• Не придумывай чрезмерно специфичные one-off tags, если пользователь не хочет такую taxonomy.
• Не смешивай frontmatter и inline tags случайно, если у vault есть понятная существующая конвенция.

Перемещение и переименование заметок

Перемещение или переименование заметок может ломать links в Markdown, embeds, canvases или внешних references. Считай это операцией повышенного риска.

Workflow:

1. Найди incoming links на название заметки перед move/rename.
2. Перемещай или переименовывай только после того, как target path ясен.
3. Обнови affected wikilinks, если visible title меняется.
4. Проверь unresolved links после операции.

Если vault использует Obsidian automatic link update, не считай, что он сработает при filesystem-only edits. Обновляй links явно, когда нужно.

MOCs и index notes

MOC, maps of content и index notes должны помогать навигации, а не дублировать весь vault.

Хорошая структура MOC:

# Topic MOC

## Core notes
- [[Important Note]] — почему важно
- [[Another Note]] — короткий контекст

## Related areas
- [[Adjacent Topic MOC]]

## Open questions
- ...

Создавай MOC, когда:

• у папки или темы достаточно заметок, чтобы требовалась навигация;
• пользователь просит map, index, overview или cleanup knowledge graph;
• demo vault нужны видимые hub nodes.

Demo vault с кластерами папок

Когда пользователь просит собрать или наполнить test/demo vault, где должны быть отдельные, но связанные области знаний:

1. Создай конкретные folder clusters с 3-5 заметками на папку и одним MOC hub note на папку.
2. Добавь frontmatter или inline tags в каждую заметку, чтобы tag pane и graph показывали metadata.
3. Добавь internal links в обе стороны между папками.
4. Добавь links из каждого MOC к заметкам внутри той же папки и к MOC других папок.
5. Добавь несколько content-level bridge notes между папками.
6. Избегай fake unresolved wikilinks.
7. Для читаемости graph допустимо записать .obsidian/graph.json с colorGroups по path:<folder> и hideUnresolved: true, сохранив важные пользовательские настройки, если редактируешь реальный vault.
8. Перед отчётом проверь механически: количество Markdown-заметок по папкам, MOC count, total wikilinks, cross-folder wikilinks и unresolved link targets.

Для проверки graph hygiene достаточно маленького Python regex pass по [[...]] links.

Рецепты проверки

Проверить unresolved wikilinks

Запусти из vault root или передай vault root в маленький скрипт:

import pathlib, re
vault = pathlib.Path("/absolute/path/to/vault")
notes = {p.stem for p in vault.rglob("*.md")}
unresolved = {}
for path in vault.rglob("*.md"):
    text = path.read_text(encoding="utf-8", errors="ignore")
    for raw in re.findall(r"\[\[([^\]]+)\]\]", text):
        target = raw.split("|", 1)[0].split("#", 1)[0].strip()
        if target and target not in notes:
            unresolved.setdefault(str(path.relative_to(vault)), set()).add(target)
for note, targets in sorted(unresolved.items()):
    print(note)
    for target in sorted(targets):
        print(f"  - {target}")

Посчитать заметки по папкам

import collections, pathlib
vault = pathlib.Path("/absolute/path/to/vault")
counts = collections.Counter(str(p.relative_to(vault).parent) for p in vault.rglob("*.md"))
for folder, count in sorted(counts.items()):
    print(f"{folder}: {count}")

Частые ошибки

1. Использовать unresolved $OBSIDIAN_VAULT_PATH в file tools. Сначала resolve в absolute path.
2. Создавать fake wikilinks. Они становятся unresolved graph nodes. Линкуй только реальные или намеренно созданные заметки.
3. Овертегать. Теги должны улучшать retrieval, а не украшать текст.
4. Игнорировать existing vault conventions. Сначала посмотри соседние заметки, потом вводи frontmatter, date formats, folder names или naming style.
5. Слепо создавать дубликаты. Перед созданием новой заметки ищи по filenames.
6. Перемещать заметки без обновления links. Filesystem moves не гарантируют Obsidian-style link updates.
7. Отчитываться об успехе без reread или verification. После создания или правок перечитай изменённый файл или запусти структурную проверку.

Checklist проверки

Перед финальным ответом по Obsidian-задаче:

• Vault path resolved в конкретный absolute path.
• Existing notes/folders inspected перед созданием новой структуры.
• File writes остались внутри intended vault.
• Новые заметки используют naming и metadata conventions vault, если они видны.
• Wikilinks указывают на существующие или намеренно созданные заметки.
• Tags полезны и консистентны с existing style.
• Changed files reread или mechanically verified.
• Unresolved links, duplicate notes или risky moves clearly reported.