Skills

На этой странице Навыки (Skills) — это предпочтительный способ добавления новых возможностей в Hermes Agent. Их проще создавать, чем инструменты (tools), они не требуют изменений кода агента и могут быть опубликованы для сообщества.

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

Используйте Навык, когда: * Возможность можно описать как инструкции + shell-команды + существующие инструменты * Он оборачивает внешний CLI или API, который агент может вызывать через terminal или web_extract * Он не требует собственной интеграции на Python или управления API-ключами, встроенными в агента * Примеры: поиск по arXiv, git-процессы, управление Docker, обработка PDF, email через CLI-инструменты

Используйте Инструмент, когда: * Требуется сквозная интеграция с API-ключами, потоками аутентификации или многокомпонентной конфигурацией * Нужна собственная логика обработки, которая должна выполняться точно каждый раз * Он обрабатывает бинарные данные, потоки или события реального времени * Примеры: автоматизация браузера, TTS, анализ изображений

Структура каталога навыка​

Встроенные навыки находятся в skills/, сгруппированные по категориям. Официальные опциональные навыки используют ту же структуру в optional-skills/: [code] skills/
├── research/
│ └── arxiv/
│ ├── SKILL.md # Обязательно: основные инструкции
│ └── scripts/ # Опционально: вспомогательные скрипты
│ └── search_arxiv.py
├── productivity/
│ └── ocr-and-documents/
│ ├── SKILL.md
│ ├── scripts/
│ └── references/
└── ...

[/code]

Формат SKILL.md​

[code] ---
name: my-skill
description: Краткое описание (показывается в результатах поиска навыков)
version: 1.0.0
author: Ваше Имя
license: MIT
platforms: [macos, linux] # Опционально — ограничение по ОС
# Допустимые значения: macos, linux, windows
# Если опущено, загружается на всех платформах (по умолчанию)
metadata:
hermes:
tags: [Категория, Подкатегория, Ключевые_слова]
related_skills: [имя-другого-навыка]
requires_toolsets: [web] # Опционально — показывать только при активных наборах инструментов
requires_tools: [web_search] # Опционально — показывать только при доступных инструментах
fallback_for_toolsets: [browser] # Опционально — скрывать при активных наборах инструментов
fallback_for_tools: [browser_navigate] # Опционально — скрывать при наличии инструментов
config: # Опционально — настройки config.yaml, необходимые навыку
- key: my.setting
description: "Что контролирует эта настройка"
default: "разумное-значение-по-умолчанию"
prompt: "Текст запроса для настройки"
required_environment_variables: # Опционально — переменные окружения, необходимые навыку
- name: MY_API_KEY
prompt: "Введите ваш API-ключ"
help: "Получить можно на https://example.com"
required_for: "Доступ к API"
---

# Заголовок навыка

Краткое введение.

## Когда использовать  
Условия срабатывания — когда агенту следует загрузить этот навык?

## Краткая справка  
Таблица стандартных команд или вызовов API.

## Процедура  
Пошаговые инструкции для агента.

## Подводные камни  
Известные режимы сбоев и способы их обработки.

## Проверка  
Как агент подтверждает, что всё сработало.

[/code]

Платформозависимые навыки​

Навыки могут ограничивать себя конкретными операционными системами с помощью поля platforms: [code] platforms: [macos] # только macOS (например, iMessage, Apple Reminders)
platforms: [macos, linux] # macOS и Linux
platforms: [windows] # только Windows

[/code] Если поле задано, навык автоматически скрывается из системного промпта, skills_list() и слэш-команд на несовместимых платформах. Если поле опущено или пустое, навык загружается на всех платформах (обратная совместимость).

Условная активация навыков​

Навыки могут объявлять зависимости от конкретных инструментов или наборов инструментов. Это контролирует, будет ли навык показан в системном промпте для данной сессии. [code] metadata:
hermes:
requires_toolsets: [web] # Скрыть, если набор инструментов web НЕ активен
requires_tools: [web_search] # Скрыть, если инструмент web_search НЕ доступен
fallback_for_toolsets: [browser] # Скрыть, если набор инструментов browser активен
fallback_for_tools: [browser_navigate] # Скрыть, если browser_navigate доступен

[/code] Поле| Поведение
---|---
requires_toolsets| Навык скрывается, когда ЛЮБОЙ из перечисленных наборов инструментов не доступен
requires_tools| Навык скрывается, когда ЛЮБОЙ из перечисленных инструментов не доступен
fallback_for_toolsets| Навык скрывается, когда ЛЮБОЙ из перечисленных наборов инструментов доступен
fallback_for_tools| Навык скрывается, когда ЛЮБОЙ из перечисленных инструментов доступен
Пример использования fallback_for_*: Создайте навык, который служит обходным решением, когда основной инструмент недоступен. Например, навык duckduckgo-search с fallback_for_tools: [web_search] показывается только тогда, когда инструмент веб-поиска (требующий API-ключ) не настроен. Пример использования requires_*: Создайте навык, который имеет смысл только при наличии определённых инструментов. Например, навык для парсинга веб-страниц с requires_toolsets: [web] не будет загромождать промпт, когда веб-инструменты отключены.

Требования к переменным окружения​

Навыки могут объявлять необходимые им переменные окружения. Когда навык загружается через skill_view, его обязательные переменные автоматически регистрируются для проброса в изолированные среды выполнения (terminal, execute_code). [code] required_environment_variables:
- name: TENOR_API_KEY
prompt: "Tenor API ключ" # Показывается при запросе у пользователя
help: "Получите ключ на https://tenor.com" # Текст справки или URL
required_for: "Функциональность поиска GIF" # Для чего нужна эта переменная

[/code] Каждая запись поддерживает: * name (обязательно) — имя переменной окружения * prompt (опционально) — текст запроса при вводе значения пользователем * help (опционально) — текст справки или URL для получения значения * required_for (опционально) — описание того, для какой функции нужна эта переменная

Пользователи также могут вручную настроить переменные для проброса в config.yaml: [code] terminal:
env_passthrough:
- MY_CUSTOM_VAR
- ANOTHER_VAR

[/code] Примеры навыков только для macOS см. в skills/apple/.

Безопасная настройка при загрузке​

Используйте required_environment_variables, когда навыку требуется API-ключ или токен. Отсутствующие значения не скрывают навык из обнаружения. Вместо этого Hermes безопасно запрашивает их при загрузке навыка в локальном CLI. [code] required_environment_variables:
- name: TENOR_API_KEY
prompt: Tenor API ключ
help: Получите ключ на https://developers.google.com/tenor
required_for: полная функциональность

[/code] Пользователь может пропустить настройку и продолжить загрузку навыка. Hermes никогда не раскрывает исходное секретное значение модели. Сессии шлюза и мессенджеров показывают локальные инструкции по настройке вместо сбора секретов в канале связи. Проброс в песочницу Когда ваш навык загружен, все объявленные required_environment_variables, которые установлены, автоматически пробрасываются в песочницы execute_code и terminal — включая удалённые бэкенды, такие как Docker и Modal. Скрипты вашего навыка могут получить доступ к $TENOR_API_KEY (или os.environ["TENOR_API_KEY"] в Python) без необходимости дополнительной настройки. Подробнее см. Проброс переменных окружения. Устаревший prerequisites.env_vars остаётся поддерживаемым псевдонимом для обратной совместимости.

Настройки конфигурации (config.yaml)​

Навыки могут объявлять несекретные настройки, которые хранятся в config.yaml в пространстве имён skills.config. В отличие от переменных окружения (секретов, хранящихся в .env), настройки конфигурации предназначены для путей, предпочтений и других нечувствительных значений. [code] metadata:
hermes:
config:
- key: myplugin.path
description: Путь к каталогу данных плагина
default: "~/myplugin-data"
prompt: Путь к каталогу данных плагина
- key: myplugin.domain
description: Домен, с которым работает плагин
default: ""
prompt: Домен плагина (например, AI/ML исследования)

[/code] Каждая запись поддерживает: * key (обязательно) — dotpath для настройки (например, myplugin.path) * description (обязательно) — объясняет, что контролирует настройка * default (опционально) — значение по умолчанию, если пользователь не настроил его * prompt (опционально) — текст запроса, показываемый во время hermes config migrate; если не указан, используется description

Как это работает: 1. Хранение: Значения записываются в config.yaml в skills.config.<key>: [code] skills:
config:
myplugin:
path: ~/my-data

[/code] 2. Обнаружение: hermes config migrate сканирует все включённые навыки, находит ненастроенные параметры и запрашивает пользователя. Настройки также отображаются в hermes config show в разделе «Настройки навыков». 3. Внедрение во время выполнения: Когда навык загружается, его значения конфигурации разрешаются и добавляются к сообщению навыка: [code] [Конфигурация навыка (из ~/.hermes/config.yaml):
myplugin.path = /home/user/my-data
]

[/code] Агент видит настроенные значения без необходимости читать config.yaml самостоятельно. 4. Ручная настройка: Пользователи также могут устанавливать значения напрямую: [code] hermes config set skills.config.myplugin.path ~/my-data

[/code]

Когда что использовать Используйте required_environment_variables для API-ключей, токенов и других секретов (хранятся в ~/.hermes/.env, никогда не показываются модели). Используйте config для путей, предпочтений и нечувствительных настроек (хранятся в config.yaml, видны в config show).

Требования к файлам учётных данных (OAuth-токены и т.д.)​

Навыки, использующие OAuth или файловые учётные данные, могут объявлять файлы, которые необходимо монтировать в удалённые песочницы. Это относится к учётным данным, хранящимся в виде файлов (не переменных окружения) — обычно это файлы OAuth-токенов, созданные скриптом настройки. [code] required_credential_files:
- path: google_token.json
description: Google OAuth2 токен (создан скриптом настройки)
- path: google_client_secret.json
description: Учётные данные Google OAuth2 клиента

[/code] Каждая запись поддерживает: * path (обязательно) — путь к файлу относительно ~/.hermes/ * description (опционально) — объясняет, что это за файл и как он создаётся

При загрузке Hermes проверяет, существуют ли эти файлы. Отсутствующие файлы вызывают setup_needed. Существующие файлы автоматически: * Монтируются в Docker контейнеры как read-only bind mounts * Синхронизируются в Modal песочницы (при создании + перед каждой командой, чтобы OAuth работал в середине сессии) * Доступны на локальном бэкенде без специальной обработки

Когда что использовать Используйте required_environment_variables для простых API-ключей и токенов (строки, хранящиеся в ~/.hermes/.env). Используйте required_credential_files для файлов OAuth-токенов, секретов клиента, JSON-файлов сервисных аккаунтов, сертификатов или любых учётных данных, которые являются файлами на диске. Полный пример использования обоих подходов см. в skills/productivity/google-workspace/SKILL.md.

Рекомендации по созданию навыков​

Без внешних зависимостей​

Предпочитайте Python из стандартной библиотеки, curl и существующие инструменты Hermes (web_extract, terminal, read_file). Если необходима зависимость, документируйте шаги по установке в навыке.

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

Помещайте самый распространённый рабочий процесс первым. Крайние случаи и продвинутое использование размещайте внизу. Это снижает расход токенов для типовых задач.

Включайте вспомогательные скрипты​

Для парсинга XML/JSON или сложной логики включайте вспомогательные скрипты в scripts/ — не рассчитывайте, что LLM будет каждый раз писать парсеры на месте.

Ссылки на встроенные скрипты из SKILL.md​

Когда навык загружается, активационное сообщение показывает абсолютный путь к каталогу навыка как [Skill directory: /abs/path], а также заменяет два шаблонных токена в любом месте тела SKILL.md: Токен| Заменяется на
---|---
${HERMES_SKILL_DIR}| Абсолютный путь к каталогу навыка
${HERMES_SESSION_ID}| Идентификатор активной сессии (остаётся как есть, если сессии нет)
Таким образом, SKILL.md может указать агенту запустить встроенный скрипт напрямую с помощью: [code] Для анализа входных данных выполните:

    node ${HERMES_SKILL_DIR}/scripts/analyse.js <входные_данные>

[/code] Агент видит подставленный абсолютный путь и вызывает инструмент terminal с готовой к выполнению командой — никаких вычислений путей или лишних запросов skill_view. Отключить подстановку глобально можно с помощью skills.template_vars: false в config.yaml.

Встраиваемые shell-сниппеты (опционально)​

Навыки также могут встраивать shell-сниппеты, написанные как !cmd` в теле SKILL.md. Если эта функция включена, stdout каждого сниппета встраивается в сообщение до того, как агент его прочитает, так что навыки могут внедрять динамический контекст: [code] Текущая дата: !date -u +%Y-%m-%dВетка Git: !git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD`

[/code] Эта функция по умолчанию выключена — любой сниппет в SKILL.md выполняется на хосте без подтверждения, поэтому включайте её только для источников навыков, которым вы доверяете: [code] # config.yaml
skills:
inline_shell: true
inline_shell_timeout: 10 # секунд на сниппет

[/code] Сниппеты выполняются с каталогом навыка в качестве рабочего, а вывод ограничен 4000 символов. Сбои (таймауты, ненулевой код возврата) отображаются как короткий маркер [inline-shell error: ...] вместо поломки всего навыка.

Тестирование​

Запустите навык и проверьте, что агент правильно следует инструкциям: [code] hermes chat --toolsets skills -q "Используй навык X, чтобы сделать Y"

[/code]

Где должен жить навык?​

Встроенные навыки (в skills/) поставляются с каждой установкой Hermes. Они должны быть полезны большинству пользователей: * Обработка документов, веб-исследования, типовые процессы разработки, системное администрирование * Регулярно используются широким кругом людей

Если ваш навык официальный и полезный, но не является универсально необходимым (например, интеграция с платным сервисом, ресурсоёмкая зависимость), поместите его в optional-skills/ — он поставляется с репозиторием, доступен для обнаружения через hermes skills browse (с пометкой «официальный») и устанавливается со встроенным доверием. Если ваш навык специализированный, создан сообществом или нишевый, он лучше подходит для Skills Hub — загрузите его в реестр и делитесь им через hermes skills install.

Публикация навыков​

В Skills Hub​

[code] hermes skills publish skills/my-skill --to github --repo owner/repo

[/code]

В пользовательский репозиторий​

Добавьте свой репозиторий как tap: [code] hermes skills tap add owner/repo

[/code] Пользователи смогут искать и устанавливать навыки из вашего репозитория.

Сканирование безопасности​

Все навыки, установленные из хаба, проходят сканирование безопасности, которое проверяет: * Паттерны эксфильтрации данных * Попытки инъекции в промпт * Деструктивные команды * Shell-инъекции

Уровни доверия: * builtin — поставляется с Hermes (всегда доверенный) * official — из optional-skills/ в репозитории (встроенное доверие, без предупреждения о стороннем источнике) * trusted — из openai/skills, anthropics/skills * community — неопасные находки можно переопределить с помощью --force; «опасные» вердикты остаются заблокированными

Hermes теперь может потреблять сторонние навыки из нескольких внешних моделей обнаружения: * прямые GitHub-идентификаторы (например, openai/skills/k8s) * идентификаторы skills.sh (например, skills-sh/vercel-labs/json-render/json-render-react) * общеизвестные конечные точки, обслуживаемые из /.well-known/skills/index.json

Если вы хотите, чтобы ваши навыки были обнаруживаемы без установщика, специфичного для GitHub, рассмотрите возможность обслуживания их через общеизвестную конечную точку в дополнение к публикации в репозитории или маркетплейсе. * Навык или Инструмент? * Структура каталога навыка * Формат SKILL.md * Платформозависимые навыки * Условная активация навыков * Требования к переменным окружения * Безопасная настройка при загрузке * Настройки конфигурации (config.yaml) * Требования к файлам учётных данных (OAuth-токены и т.д.) * Рекомендации по созданию навыков * Без внешних зависимостей * Постепенное раскрытие * Включайте вспомогательные скрипты * Тестирование * Где должен жить навык? * Публикация навыков * В Skills Hub * В пользовательский репозиторий * Сканирование безопасности