Создание навыков агента Hermes — структура файла SKILL.md и рекомендации по最佳

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

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

Hermes является частью более широкой кластерной системы AI Systems: Self-Hosted Assistants, RAG, and Local Infrastructure, где ассистенты рассматриваются не как единый интерфейс чата, а как системы, построенные на основе вывода (inference), поиска (retrieval), памяти и инструментов. Пути установки, подключение провайдеров, поведение шлюза и структура папки ~/.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-ключей и потоков аутентификации, детерминированная обработка бинарных данных, потоковая передача (streaming) или Python, который должен выполняться одинаковым образом каждый раз.

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

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

Навыки отвечают на вопрос как запустить рабочий процесс; ограниченная основная память 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 становится маршрутом слэша и ключом индекса; он должен быть в нижнем регистре с дефисами и соответствовать документированному лимиту длины. description — это единственный текст, за который многие сессии платят на нулевом уровне, поэтому он должен читаться как результат поиска или строка роутера («когда бэкапы кажутся устаревшими, проверьте последний архив и контрольную сумму»), а не как первый абзац блога.

Необязательные ключи верхнего уровня, такие как version, author и license, помогают упаковке хаба и аудиту. Список 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 все равно давал агенту что-то actionable.

Ниже приведен минимальный 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)
---

# Backup archive spot-check

## When to use

Use when the user asks to confirm backups ran, to audit the latest archive on disk, or to catch empty or stale backup files before a restore drill.

## Quick reference

- Latest archive directory is configured under `skills.config.backup_check.archive_dir` (set via `hermes config migrate` if declared in metadata).
- Default check uses `ls` by mtime and `test -s` for non-empty files.

## Procedure

1. Resolve the archive directory from skill config or ask the user once if unset.
2. List the most recently modified file matching the expected pattern (for example `*.tar.zst`).
3. Confirm the file exists, is non-empty, and record its path and size for the reply.
4. If a checksum file exists beside the archive, verify it with the documented tool (for example `sha256sum -c`).

## Pitfalls

- Empty files can still have a recent mtime if a failed job touched the path; always check size.
- Relative paths break when the terminal cwd is not the backup host; use absolute paths in config.

## Verification

The user should see the latest archive path, byte size, and either a checksum OK line or an explicit note that no `.sha256` sidecar was found.

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

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

Практическая структура, которая выдерживает частичную загрузку: When to use (триггеры простым языком), Quick reference (команды, переменные окружения, пути к файлам), Procedure (упорядоченные шаги, которые агент не должен импровизировать), Pitfalls (известные режимы отказа) и Verification (как выглядит «зеленый» результат). Нарративная история, дампы журналов изменений вендоров и таблицы опций на двадцать строк должны находиться в 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} лучше, чем заставлять модель выводить парсеры заново при каждом запуске. Если вам действительно нужен пакет, укажите команду установки в Procedure, повторите симптом отказа в Pitfalls и дайте команду Verification, которая громко падает, когда зависимость отсутствует.

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

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

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

Организационные развертывания обычно сочетают приватный 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, ваш текст When to use или description, вероятно, не соответствует тому, как люди формулируют запросы.

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