Создание навыков для агента Hermes — структура и лучшие практики файла SKILL.md

Hermes Agent рассматривает навыки (skills) как основной способ обучения повторяемым рабочим процессам. Официальная документация описывает их как документы знаний по запросу, соответствующие открытому формату agentskills.io, загружаемые через механизм постепенного раскрытия, при котором модель сначала видит небольшой индекс и загружает полные инструкции только тогда, когда задача действительно этого требует.

Создание навыков связано скорее не с изощрённой формулировкой, а с упаковкой — вы сообщаете рантайму, когда загружать процедуру, какой порядок шагов считается завершённым и как отличить успешное выполнение от молчаливого сбоя. В этой статье мы сосредоточимся на структуре SKILL.md, поддерживающих папках, правилах видимости и разделении секретных и не секретных настроек — деталях, которые определяют, появится ли навык в командах /slash, переживёт установку из хабa или тихо исчезнет в CI.

Hermes находится в рамках более широкого кластера AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructure, где ассистенты рассматриваются как системы, построенные из компонентов вывода, извлечения, памяти и инструментов, а не как единая поверхность чата. Пути установки, подключение провайдеров, поведение шлюза и структура ~/.hermes подробно описаны в руководстве Hermes AI Assistant - Install, Setup, Workflow, and Troubleshooting; повседневная эргономика оболочки — hermes skills, профили, шлюз, память — удобнее просматривать в Hermes Agent CLI cheat sheet — commands, flags, and slash shortcuts. В реальных развёртываниях навыки наследуют изоляцию от профилей (отдельные конфигурации, секреты, памяти и деревья навыков). Hermes AI Assistant Skills for Real Production Setups утверждает, что именно профили, а не отдельные markdown-файлы должны быть единицей владения; имейте это в виду при именовании навыков и решении о том, что помещать в общие external_dirs, а что — в отдельный профиль.

Навык или инструмент?

Официальные рекомендации прямолинейны. Используйте навык, когда способность состоит преимущественно из текстовых инструкций и команд оболочки, которые Hermes уже предоставляет — обёртка над CLI, управление git, вызов curl или использование web_extract для структурированного получения данных. Используйте инструмент, когда требуется тесная интеграция для API-ключей и потоков аутентификации, детерминированная обработка бинарных данных, стриминг или Python, который должен выполнять одинаково каждый раз.

Эта граница имеет практическое значение, потому что навыки поставляются без изменения кода агента, тогда как инструменты несут накладные расходы на проверку и выпуск. Большинство команд выигрывают от начала с навыка, а затем продвижения только хрупкого ядра в инструмент, когда режимы сбоя становятся очевидными (циклы обновления авторизации, бинарные парсеры, строгая идемпотентность). Для более широкого архитектурного вопроса о том, когда использовать Agent Skill вместо MCP-сервера — особенно вокруг учётных данных, живого состояния и транзакционных записей — см. нашу раму принятия решений Agent Skills vs MCP Servers.

Процедуры против курируемой памяти

Навыки отвечают на вопрос как выполнить рабочий процесс; ограниченная основная память Hermes отвечает на вопрос что уже согласовано о пользователе и проекте. Навык загружается, когда задача соответствует его описанию; MEMORY.md и USER.md остаются в промпте как небольшой курируемый слой фактов. Эти два механизма дополняют друг друга, а не конкурируют, полная картина снимков, ограничений и внешних провайдеров изложена в Hermes Agent Memory System: How Persistent AI Memory Actually Works.

Анатомия директории навыка

На диске каждый навык представляет собой папку под ~/.hermes/skills/, часто вложенную в категорию, такую как devops/ или research/. Hermes ожидает SKILL.md на кончике; всё остальное — необязательная структура, которую вы добавляете, когда инструкции иначе бы рассыпались. Обычный паттерн: references/ для длинных таблиц или документации вендоров, templates/ для скелетов вывода, scripts/ для детерминированных помощников и assets/ для статических файлов, которые агент не должен повторно загружать.

Эта структура отражает, как работает постепенное раскрытие на практике: агент может оставаться на основном файле, пока ему действительно не понадобится глубокий раздел. Сохранение «happy path» в SKILL.md и перенос редко используемых деталей в references/ — один из самых дешёвых способов защитить бюджет токенов.

Hermes также может объединять внешние директории навыков через skills.external_dirs в config.yaml. Эти пути сканируются для обнаружения, но агент по-прежнему пишет через skill_manage в основное дерево ~/.hermes/skills/. Локальные имена затеняют внешние, поэтому если вы «исправите» общий навык в домашней директории, коллеги, использующие тот же внешний репозиторий, не увидят вашего изменения, пока не удалят или не переименуют локальную копию — частый источник путаницы «работает на моей машине».

Frontmatter SKILL.md, выживающий при проверке

Тело SKILL.md — это Markdown; открывающий блок должен быть валидным YAML между разделителями ---. Реальные навыки накапливают длинные заборчатые примеры, поэтому небольшие привычки из Markdown Code Blocks: Complete Guide with Syntax, Languages & Examples — последовательные языковые теги, читаемые выдержки, компактные заборы — сохраняют большие файлы поддерживаемыми для людей и немного более лёгкими для модели при сканировании.

Обязательные поля — name и description. name становится маршрутом slash и ключом индекса; он остаётся в нижнем регистре с дефисами и должен соблюдать документированный предел длины. description — это единственный текст, за который многие сессии когда-либо платят на нулевом уровне, поэтому он должен читаться как результат поиска или строка маршрутизации («когда резервные копии кажутся устаревшими, проверьте последний архив и контрольную сумму»), а не первый абзац блога.

Необязательные ключи верхнего уровня, такие как version, author и license, помогают упаковке хабa и аудиту. Список platforms (macos, linux, windows) острее, чем кажется — когда установлен, Hermes полностью исключает навык на несовпадающих хостах, поэтому навык, который «работает на моём Mac», может исчезнуть в Linux CI без сообщения об ошибке, кроме более короткого списка навыков.

Специфичные для Hermes настройки находятся под metadata.hermes: tags, related_skills и поля условной видимости в следующем разделе. required_environment_variables объявляет секреты, которые должны оказаться в .env и передаваться в песочницы; required_credential_files покрывает файлы токенов OAuth и другие учётные данные на диске, которые должны монтироваться в Docker или Modal; metadata.hermes.config объявляет не секретные предпочтения, хранимые под skills.config в config.yaml.

Официальная документация подчёркивает дисциплину размера по причине. Сократите description до его бюджета, вынесите процедуру вперёд и перенесите исторические заметки или огромные матрицы опций в references/, чтобы частичный skill_view всё равно давал агенту что-то выполнимое.

Ниже приведён минимальный SKILL.md, который можно поместить в ~/.hermes/skills/devops/backup-check/SKILL.md (или любую другую папку категории) и итерировать от него.

---
name: backup-check
description: Verify nightly backup archives exist, are non-empty, and pass a quick checksum spot-check on the latest file.
version: 1.0.0
metadata:
  hermes:
    tags: [devops, backups, shell]
    requires_toolsets: [terminal]
    config:
      - key: backup_check.archive_dir
        description: Absolute path to the directory that holds backup archives
        default: "/var/backups"
        prompt: Backup archive directory (absolute path)
---

# Проверка резервных архивов

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

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

## Быстрая справка

- Директория последнего архива настроена в `skills.config.backup_check.archive_dir` (устанавливается через `hermes config migrate`, если объявлена в metadata).
- Проверка по умолчанию использует `ls` по mtime и `test -s` для не пустых файлов.

## Процедура

1. Определите директорию архивов из конфигурации навыка или спросите пользователя один раз, если не установлено.
2. Перечислите файл с самым недавним изменением, соответствующий ожидаемому паттерну (например `*.tar.zst`).
3. Подтвердите, что файл существует, не пуст, и запишите его путь и размер для ответа.
4. Если рядом с архивом существует файл контрольной суммы, проверьте его с помощью документированного инструмента (например `sha256sum -c`).

## Подводные камни

- Пустые файлы всё ещё могут иметь недавний mtime, если неудачная задача коснулась пути; всегда проверяйте размер.
- Относительные пути ломаются, когда cwd терминала не является хостом резервного копирования; используйте абсолютные пути в конфигурации.

## Верификация

Пользователь должен увидеть путь к последнему архиву, размер в байтах и либо строку ОК контрольной суммы, либо явную заметку о том, что файл-компаньон `.sha256` не найден.

Постепенное раскрытие на практике

Постепенное раскрытие — это разница между библиотекой навыков, которая ощущается отзывчивой, и той, которая сжигает тысячи токенов до первого сообщения пользователя. Hermes проходит три концептуальных шага: компактный каталог (имена и короткие описания), полный SKILL.md, когда задача совпадает, и — только при необходимости — фрагмент файла справки через пути skill_view. Предполагайте, что нулевой уровень — это всё, что модель прочитает, пока она явно не обязуется; каждое предложение в description и первый экран текста тела должны помогать маршрутизации, а не повествованию.

Практический план, выживающий при частичной загрузке: Когда использовать (триггеры простым языком), Быстрая справка (команды, переменные окружения, пути к файлам), Процедура (упорядоченные шаги, которые агент не должен импровизировать), Подводные камни (известные режимы сбоя) и Верификация (как выглядит «зелёный» результат). Нарративная история, дамп журналов изменений вендоров и таблицы опций на двадцать строк принадлежат в references/ со стабильными заголовками, чтобы агент мог извлечь один раздел.

Когда навык активируется, Hermes может переписать ${HERMES_SKILL_DIR} и ${HERMES_SESSION_ID} в теле, чтобы строки оболочки указывали на установленную папку без ручных путей. Необязательные инлайн-оболочечные сниппеты (!cmd``) могут внедрять свежий контекст (текущая ветка, свободное место на диске), но они выполняются на хосте и остаются отключёнными, если skills.inline_shell не включён — относитесь к этому флагу как к границе доверия для всего источника навыка, а не к удобной переключатель.

Условная активация и гигиена промпта

Навыки могут показываться или скрываться в зависимости от того, какие наборы инструментов или инструменты существуют в текущей сессии. requires_toolsets / requires_tools блокируют навык за возможностями, которые должны присутствовать; fallback_for_toolsets / fallback_for_tools показывают более дешёвый или локальный путь, когда премиум-интеграция отсутствует — паддинг DuckDuckGo, когда платный API веб-поиска не настроен, является каноническим примером.

Эти предикаты напрямую формируют шум промпта. Чрезмерно строгое правило requires_* скрывает навык от новичков, которые ещё не завершили настройку hermes tools; чрезмерно свободное правило fallback_for_* дублирует половину вашей библиотеки всякий раз, когда кто-то пропускает API-ключ. Полезная золотая середина — называть реальные предварительные требования, тестировать с hermes chat --toolsets skills и целенаправленно переключать ключи или наборы инструментов, наблюдая, не дышит ли список навыков так, как вы ожидаете.

Секреты, конфигурация и файлы учётных данных

Секреты должны быть объявлены в required_environment_variables. Hermes может запрашивать при загрузке навыка в локальном CLI, сохранять значения в .env и передавать их в песочницы terminal и execute_code без стриминга сырого секрета обратно в транскрипт модели. Удалённые поверхности чата отказываются собирать ключи инлайн и вместо этого направляют людей к hermes setup или ручным правкам .env — авторите текст вашего навыка так, чтобы он соответствовал этому поведению (сообщайте пользователям, что ключ требуется, а не *вставлять его в Telegram).

Не секретные предпочтения — пути по умолчанию, имена организаций, переключатели функций — принадлежат в metadata.hermes.config. Значения разрешаются в skills.config внутри config.yaml, появляются в hermes config show и приходят в сообщение навыка как разрешённые факты, чтобы модели не нужно было открывать ваш файл конфигурации посреди задачи.

Файловые учётные данные (JSON токенов OAuth, ключи сервисных учётных записей) отображаются на required_credential_files. Когда эти файлы существуют, Hermes может bind-mount их в Docker или синхронизировать в задания Modal; объявление их заранее избегает классического разрыва «скрипт работает локально, умирает в песочнице».

Поддерживающие скрипты и зависимости

Восходящее руководство наталкивает авторов на скучные зависимости: stdlib Python, curl и собственные инструменты Hermes (web_extract, read_file, terminal). Это менее о чистоте, чем о воспроизводимости — каждая дополнительная pip install — ещё один молчаливый сбой, когда агент запускается в чистом контейнере.

Когда парсинг JSON или XML капризен, короткий скрипт под scripts/ плюс путь ${HERMES_SKILL_DIR} лучше, чем просить модель повторно выводить парсеры каждый раз. Если вам действительно нужен пакет, укажите команду установки в Процедуре, повторите симптом сбоя в Подводных камнях и дайте команду Верификации, которая громко падает, когда зависимость отсутствует.

Публикация, установка из хабa и доверие

Сообщество навыков проходит через Skills Hub и другие пути обнаружения, перечисленные в руководстве пользователя — официальные необязательные навыки, GitHub slugi, записи skills.sh, индексы .well-known и сырые URL SKILL.md. Установки сканируются на очевидную эксфильтрацию, инъекцию и деструктивные паттерны; уровни доверия идут от встроенного через сообщества, и некоторые находки очищаются только с --force, тогда как худшие случаи остаются заблокированными полностью.

Форма файла SKILL.md не специфична для Hermes; IDE-центричные ассистенты используют ту же идею постепенной загрузки с другим обнаружением и триггерами. Claude Skills and SKILL.md for Developers: VS Code, JetBrains, Cursor — полезное контрастное чтение — дисциплина frontmatter и «загружать только когда релевантно» переносятся, даже когда установщик и проводка slash-команд отличаются.

Развёртывания на весь организм обычно сочетают приватный tap или общий Git-репозиторий с external_dirs для чтения без записи, сохраняя копию, доступную для записи агентом, под каждым профилем, когда skill_manage разрешено мутировать навыки на месте.

Устранение неполадок и оптимизация

Когда навык ведёт себя неправильно, пройдите этот чеклист перед переписыванием текста.

• Видимость — Подтвердите предикаты platforms, requires_* и fallback_for_*. Навык, который «работает на моём Mac», но не в Linux CI, часто является платформенным ограничением.
• Столкновения имён — Дублирующиеся имена между локальными и внешними директориями следуют локальному приоритету. Переименуйте или неймспейсите агрессивно.
• Структура обнаружения — Неправильно расположенный SKILL.md или неправильная папка категории могут полностью исключить навык из индексации.
• Нагрузка токенов — Если сессии кажутся медленными, сократите описания нулевого уровня, перенесите глубину в references/ и дедуплицируйте огромные таблицы.
• Редактирования агента — Hermes может создавать, патчить или удалять навыки через skill_manage. Относитесь к ценным навыкам как к коду: проверяйте диффы, экспортируйте снимки и сознательно сбрасывайте встроенные навыки при дрейфе обновлений.

Плотный регрессионный цикл лучше перечитывания всего файла: hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>" должен показать, что агент извлекает правильный уровень раскрытия перед импровизацией. Если он никогда не вызывает skill_view, ваш текст Когда использовать или description, вероятно, не соответствует тому, как люди формулируют запросы.

Официальные ссылки остаются авторитетными для изменений поведения — Skills System руководство пользователя для семантики рантайма, Creating Skills для правил, ориентированных на авторов, Bundled Skills Catalog для примеров копирования-вставки и agentskills.io specification для общего формата файла, с которым Hermes выравнивается.