Если вы когда-нибудь видели, как ИИ-агент портит ваше хранилище Obsidian, эта инструкция поможет.

Свой «второй мозг» я храню в Obsidian на той же системе Rocky Linux, которую использую для всего остального. Несколько месяцев Claude Code работал с моими заметками, но я не объяснял ему, как устроен Obsidian.

Он создавал обычные ссылки Markdown вместо wikilinks, игнорировал блоки callout и не понимал, что такое файл .base, когда натыкался на него. Заметки по-прежнему открывались в Obsidian, но теряли возможности, ради которых этот инструмент и выбирают.

Затем я обнаружил obsidian-skills — небольшой репозиторий, который поддерживает Steph Ango, CEO Obsidian (известный как kepano на GitHub). Он упаковывает знания, характерные для Obsidian, в формат Agent Skills. После добавления в настройки Claude Code для моего хранилища разница стала заметна сразу.

Claude начал создавать правильные wikilinks, учитывал фильтры Bases и даже применял навык Defuddle, чтобы извлекать чистый Markdown из веб-страниц вместо сброса сырого HTML в заметки.

В этом материале редакция покажет, что входит в obsidian-skills, как установить его на Ubuntu/Debian и RHEL/Rocky Linux, а также как убедиться, что агент действительно использует навыки, а не оставляет их лежать без дела в папке.

Что на самом деле делает obsidian-skills

obsidian-skills — это не плагин Obsidian, который устанавливается через браузер Community Plugins. Это набор Agent Skills — текстовых инструкций, следующих открытой спецификации Agent Skills.

Файлы рассчитаны на то, чтобы AI-агент по написанию кода прочитал их до начала работы с хранилищем. Инструменты вроде Claude Code, Codex и OpenCode поддерживают этот формат из коробки.

Сейчас репозиторий включает пять навыков, и каждый объясняет агенту отдельную часть устройства Obsidian:

  • obsidian-markdown – Описывает Obsidian Flavored Markdown, в том числе wikilinks, встраиваемые элементы, callout-блоки и YAML-свойства, которые ведут себя иначе, чем стандартный Markdown.

  • obsidian-bases – Объясняет формат .base, используемый для создания фильтрованных и основанных на формулах представлений заметок.

  • json-canvas – Охватывает открытый формат .canvas, применяемый функцией Canvas в Obsidian: узлы, связи и группы.

  • obsidian-cli – Показывает агенту, как работать с Obsidian CLI, включая задачи по разработке плагинов и тем.

  • defuddle – Помогает агенту извлекать чистый Markdown из веб-страниц вместо вставки больших объемов сырого HTML в заметки.

Без этих навыков AI-агент видит хранилище просто как набор обычных текстовых файлов. С ними он понимает синтаксис и структуру, которые лежат в основе ссылок, запросов и canvas-возможностей Obsidian.

Примечание: obsidian-skills не заменяет Obsidian и не заменяет Obsidian CLI. Он лишь даёт инструкции, которые помогают AI-агенту эффективнее работать с этими инструментами.

Предварительные требования

Перед началом убедитесь, что у вас есть:

  • Система Linux с установленным Git.

  • Node.js и npm (понадобятся только если вы планируете использовать установщик npx или команду плагинного маркетплейса Claude Code).

  • Claude Code, Codex или OpenCode уже установлены и работают.

  • Существующее хранилище Obsidian, поскольку навыки предназначены для работы именно с ним.

Если вы уже пользуетесь Claude Code с хранилищем Obsidian, вы почти готовы. Зависимость от Node.js относится лишь к одному из способов установки, рассмотренных далее.

Шаг 1. Убедитесь, что Git и Node.js установлены

Перед выбором способа установки проверьте, есть ли в системе Git и Node.js. Самый быстрый метод (npx skills) требует Node.js, тогда как ручная установка обойдётся одним Git.

git --version
node --version

Пример вывода:

git version 2.43.0
v20.14.0

Если какая-то из команд выдаёт command not found, установите недостающие пакеты.

На Ubuntu/Debian

sudo apt update
sudo apt install git nodejs npm -y

На RHEL/Rocky Linux

sudo dnf install git nodejs npm -y

sudo выполняет команду с административными привилегиями, необходимыми для установки программных пакетов в систему.

Шаг 2. Выберите способ установки

obsidian-skills предлагает три способа установки. Если вы пользуетесь только Claude Code, метод A самый быстрый, так как требует минимум настроек.

Метод A: Установка из плагинного маркетплейса Claude Code

Это самый быстрый вариант, если Claude Code — ваш единственный AI-агент. Выполните приведённые команды внутри самого Claude Code, а не в обычном терминале Linux:

/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

Вот что делают эти команды:

  • plugin marketplace add kepano/obsidian-skills добавляет GitHub-репозиторий как источник плагинов, доступный для Claude Code.

  • plugin install obsidian@obsidian-skills устанавливает плагин obsidian из этого источника.

Поскольку это слеш-команды Claude Code, привычного вывода терминала вы не увидите. Вместо него Claude Code покажет подтверждение в чате по завершении установки.

Метод B: Установщик npx skills

Этот способ запускается из обычного терминала Linux и подходит для любых AI-агентов. Вместо автоматической установки всего сразу вы проходите интерактивную настройку.

npx skills add https://github.com/kepano/obsidian-skills

Пример вывода:

Source: https://github.com/kepano/obsidian-skills.git
◇  Repository cloned
◇  Found 5 skills
◇  Select skills to install (space to toggle)
◆  Which agents do you want to install to?

Установщик делает две паузы, и обе требуют вашего участия:

  • Select skills to install: Нажмите Space, чтобы выбрать все пять навыков (defuddle, json-canvas, obsidian-bases, obsidian-cli и obsidian-markdown), затем нажмите Enter. Поскольку навыки работают совместно, улучшая взаимодействие агента с контентом Obsidian, пропускать какой-либо из них нет смысла.

  • Which agents do you want to install to?: Установщик поддерживает 73 разных агента, и одновременно отображаются лишь несколько. Группа Universal (.agents/skills) выбрана автоматически, но Claude Code может быть не виден сразу. Введите claude в поле поиска, выберите Claude Code пробелом и нажмите Enter для продолжения.

Примечание: При ручной установке (см. репозиторий) навыки Claude Code помещаются в каталог .claude внутри хранилища, а не в .agents/skills. Явный выбор Claude Code в установщике гарантирует, что файлы окажутся там, где Claude Code ожидает их найти.

После завершения установки проверьте, что навыки появились:

ls -la /path/to/your/obsidian-vault/.claude

Пример вывода:

defuddle  json-canvas  obsidian-bases  obsidian-cli  obsidian-markdown

Если каталог .claude пуст или отсутствует, проверьте .agents/skills — некоторые версии установщика помещают файлы туда.

Совет: README проекта также содержит SSH-ссылку ([[email protected]](/cdn-cgi/l/email-protection):kepano/obsidian-skills.git). Если у вас уже настроены SSH-ключи для GitHub, можете использовать её, но для большинства проще взять HTTPS-адрес, показанный выше, — он работает без дополнительных действий.

Метод C: Клонирование репозитория вручную (Claude Code, Codex или OpenCode)

Редакция предпочитает этот способ, так как он даёт полный контроль над тем, что именно копируется и куда попадает. Он одинаково хорошо работает с Claude Code, Codex и OpenCode.

Для Claude Code

Перейдите в хранилище Obsidian и клонируйте репозиторий в каталог .claude:

cd /path/to/your/obsidian-vault
git clone https://github.com/kepano/obsidian-skills.git .claude

Пример вывода:

Cloning into '.claude'...
remote: Enumerating objects: 210, done.
remote: Counting objects: 100% (210/210), done.
Receiving objects: 100% (210/210), 84.30 KiB | 2.11 MiB/s, done.

Пояснение команд:

  • cd /path/to/your/obsidian-vault перемещает вас внутрь хранилища Obsidian. Это важно, потому что именно здесь будет создан каталог .claude.

  • git clone .claude клонирует репозиторий прямо в папку с именем .claude, а не в obsidian-skills.

Для Codex

Клонируйте репозиторий во временное расположение и скопируйте только каталог skills/ в место, где Codex ожидает навыки:

git clone https://github.com/kepano/obsidian-skills.git /tmp/obsidian-skills
cp -r /tmp/obsidian-skills/skills/* ~/.codex/skills/

Для OpenCode

Клонируйте весь репозиторий в каталог навыков OpenCode:

git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

Предупреждение: Для OpenCode нельзя копировать только внутреннюю папку skills/. OpenCode ожидает следующую структуру: ~/.opencode/skills/obsidian-skills/skills//SKILL.md. Копирование лишь подкаталога skills/ нарушает эту раскладку, и OpenCode не загрузит навыки корректно. После клонирования перезапустите OpenCode, так как он обнаруживает новые навыки только при запуске.

Если вы хотите разобраться, как Claude Code обнаруживает и загружает подобные навыки «под капотом», курс Pro TecMint Claude Code for Linux Sysadmins подробно освещает этот процесс.

Шаг 3. Проверьте, что Claude Code читает навыки

Установка файлов ещё не означает, что Claude Code их использует. Разумно удостовериться, что навыки загружены корректно.

Запустите сеанс Claude Code из корня хранилища Obsidian:

claude

Когда сеанс начнётся, задайте Claude Code простой вопрос:

Какие навыки, специфичные для Obsidian, тебе сейчас доступны?

Если всё настроено правильно, Claude Code перечислит названия навыков:

  • obsidian-markdown

  • obsidian-bases

  • json-canvas

  • obsidian-cli

  • defuddle

Обычно он также кратко описывает назначение каждого.

Если Claude Code отвечает, будто ничего не знает о специфичном синтаксисе Obsidian, скорее всего, навыки не загружаются. Самые частые причины:

  • Неправильное имя каталога. Оно должно называться именно .claude.

  • Вы запустили Claude Code не из корневого каталога хранилища, поэтому он не может найти папку .claude.

Как только Claude Code распознает навыки, он сможет работать с хранилищем, используя синтаксис и возможности Obsidian, а не воспринимая всё как простые текстовые файлы.

Шаг 4. Примените навык на практике

Проще всего оценить пользу obsidian-skills — дать Claude Code задание, требующее знаний, характерных именно для Obsidian. Это как раз те задачи, с которыми обычный AI-агент, знакомый только с Markdown, часто ошибается.

Например, редакция протестировала навык на Base-файле для отслеживания статуса глав курса Pro TecMint.

Внутри Claude Code мы использовали такой промпт:

Создай Obsidian Base-файл, который фильтрует заметки с тегом #course-chapter и группирует их по свойству "status" со значениями Draft, Review и Published.

С загруженным навыком obsidian-bases Claude Code с первой попытки сгенерировал корректный файл .base с правильным фильтром и структурой группировки.

Без навыка он обычно угадывал синтаксис и выдавал нечто, что выглядит правдоподобно, но не работает с функцией Bases в Obsidian.

Совет: Если вы часто сохраняете веб-контент в хранилище, попробуйте навык defuddle. Попросите Claude Code: Извлеки чистое содержимое этой страницы в новую заметку. Затем сравните результат с обычным копированием и вставкой. Вы почти наверняка заметите гораздо меньше мусора — реклама, навигационные меню и прочие ненужные элементы страницы будут удалены автоматически.

Обновление obsidian-skills

obsidian-skills активно сопровождается, новые навыки и исправления добавляются регулярно. Если вы устанавливали его клонированием репозитория вручную, обновляйте так же, как любой другой Git-репозиторий:

cd ~/vault-path/.claude
git pull origin main

Команда переходит в каталог .claude и забирает последние изменения из ветки main.

Если obsidian-skills был установлен через плагинный маркетплейс Claude Code, выполнять git pull не нужно. В этом случае обновления обрабатываются собственным механизмом обновления плагинов Claude Code, поскольку он управляет файлами за вас.

Заключение

Теперь obsidian-skills дал вашему AI-агенту знания, необходимые для понимания устройства хранилища Obsidian, вместо того чтобы воспринимать его как набор обычных текстовых файлов. Это может показаться небольшим улучшением, но в повседневной работе разница ощутима.

Wikilink, который разрешается правильно, Base-файл, принимаемый Obsidian без ошибок, или Canvas-файл с корректно структурированными узлами и связями — всё это зависит от того, понимает ли агент форматы Obsidian с самого начала. А значит, меньше времени уходит на исправление ошибок и больше — на работу с заметками.

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

Если же вы пошли дальше и создали собственные навыки под свой рабочий процесс, например, для поддержки конкретного плагина Obsidian или нестандартного формата файлов, мы будем искренне рады услышать о вашем подходе.