Создание навыков

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

Что выбрать: навыки или инструмент?

Создавайте навык, когда: - Возможность может быть выражена как инструкция + командная оболочка + дополнительные инструменты. - Он оборачивает внешний CLI или API, который агент может вызвать через terminal или web_extract - Он не требует пользовательской поддержки Python или API-ключей управления, подключенных к агенту. - Примеры: поиск по arXiv, git-воркфлоу, управление Docker, обработка PDF, электронная почта через CLI-инструменты.

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

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

Встроенные навыки находятся в разделе «навыки», сгруппированные по категориям. Официальные опциональные навыки используют ту же структуру в optional-skills/:

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

Формат SKILL.md

---
name: my-skill
description: Краткое описание (показывается в результатах поиска навыков)
version: 1.0.0
author: Ваше Имя
license: MIT
platforms: [macos, linux]          # Опционально — ограничить конкретными ОС
                                   #   Допустимые: macos, linux, windows
                                   #   Опустите для загрузки на всех платформах (по умолчанию)
metadata:
  hermes:
    tags: [Категория, Подкатегория, Ключевые слова]
    related_skills: [other-skill-name]
    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.

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

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

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

Навыки для конкретной платформы

Навыки могут ограничить себя последствиями операционными циклами с помощью полей «платформы»:

platforms: [macos]            # Только macOS (например, iMessage, Apple Reminders)
platforms: [macos, linux]     # macOS и Linux
platforms: [windows]          # Только Windows

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

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

Навыки могут объявлять в зависимости от конкретных инструментов или наборов инструментов. Это контроль, появление ли навыков в системном приглашении для данной сессии.

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

Сценарий использования fallback_for_*: создайте навык, который будет применяться в обходных решениях, когда основной инструмент недоступен. Например, навыки duckduckgo-search с fallback_for_tools: [web_search] появляются только тогда, когда инструмент веб-поиска (требующий API-ключ) не настроен.

Сценарий использования requires_*: Создайте навыки, которые имеют значение только при наличии определенных инструментов. Например, навыки рабочего процесса веб-скрапинга с requires_toolsets: [web] не будут загромождать запрос, когда веб-инструменты отключены.

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

Навыки могут объявить об обеспечении переменного окружения. Когда навык загружается через skill_view, его обязательные переменные автоматически регистрируются для передачи в изолированные среды выполнения (терминал, Execute_code).

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Tenor API ключ"               # Показывается при запросе у пользователя
    help: "Получите ключ на https://tenor.com"  # Текст справки или URL
    required_for: "Функциональность поиска GIF"   # Что требует эту переменную

поддержка каждой записи: - name (обязательно) — имя переменного окружения - prompt (опционально) — текст подсказки при запросе значений у пользователя - help (опционально) — текстовая справка или URL-адрес для получения значений. - required_for (опционально) — указывает, какая функция требует эту переменную.

Пользователи также могут настроить переменные для передачи в config.yaml:

terminal:
  env_passthrough:
    - MY_CUSTOM_VAR
    - ANOTHER_VAR

См. skills/apple/ для примеров функций только для macOS.

Безопасная настройка при включении

Используйте required_environment_variables, когда навыку требуется API-ключ или токен. Отсутствующие значения не скрывают навыки обнаружения. Вместо этого Hermes безопасно запрашивает их при использовании навыков в локальном CLI.

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API ключ
    help: Получите ключ на https://developers.google.com/tenor
    required_for: полная функциональность

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

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

Навыки могут объявить несекретные настройки, которые хранятся в config.yaml в пространстве имен skills.config. В отличие от окружения окружения (которые являются секретами, хранящимися в .env), конфигурация конфигурации определяет пути, предпочтения и другие нечувствительные факторы.

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: Путь к каталогу данных плагина
        default: "~/myplugin-data"
        prompt: Путь к каталогу данных плагина
      - key: myplugin.domain
        description: Домен, в котором работает плагин
        default: ""
        prompt: Домен плагина (например, исследования AI/ML)

поддержка каждой записи: - key (обязательно) — точечный путь для настройки (например, myplugin.path) - description (обязательно) — слово, что контролирует настройку - default (опционально) — значение по умолчанию, если пользователь его не настроил - prompt (опционально) — текст подсказки, вызываемый во время hermes configmigrate; возвращается к описанию

Как это работает:

1. Хранение: Значения значений в config.yaml по пути skills.config.<key>: yaml skills: config: myplugin: path: ~/my-data

2. Обнаружение: hermes configmigrate сканирует все включенные навыки, находит ненастроенные параметры и запрашивает пользователя. Настройки также включены в hermes config show в разделе «Настройки навыков».

3. Внедрение во время выполнения: При загрузке навыка его значения определяются и включаются в сообщение навыка: [Skill config (from ~/.hermes/config.yaml): myplugin.path = /home/user/my-data ] Агент видит настроенные значения без необходимости читать config.yaml самостоятельно.

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

   💡 Tip

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

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

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

required_credential_files:
  - path: google_token.json
    description: Токен Google OAuth2 (создается скриптом настройки)
  - path: google_client_secret.json
    description: Учетные данные клиента Google OAuth2

поддержка каждой записи: - path (обязательно) — путь к файлу соответственно ~/.hermes/ - description (опционально) — мысль, что это за файл и как он создан

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

Рекомендации по навыкам

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

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

успешное раскрытие

Сначала поместите наиболее распространенный рабочий процесс. Крайние случаи и расширенное использование отсутствуют. Это умеренное использование токенов для составления задач.

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

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

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

Когда загружается навык, активационное сообщение раскрывает полный путь к каталогу навыков, как [Каталог навыков: /abs/path], а также заменяет два шаблона токенов в любом месте тела SKILL.md:

Таким образом, SKILL.md может дать агенту возможность запуска встроенного скрипта напрямую с помощью:

Чтобы проанализировать ввод, выполните:

    node ${HERMES_SKILL_DIR}/scripts/analyse.js <input>

Агент видит подставленный абсолютный путь и представляет собой инструмент «терминал» с готовой к выполнению команды — никакого компьютерного пути, никаких дополнительных обходов «skill_view». Отключите подстановку глобально с помощью skills.template_vars: false в config.yaml.

Встроенные фрагменты оболочки (opt-in)

Навыки также могут встраивать встроенные фрагменты оболочки, обозначенные как !`cmd` в теле SKILL.md. Когда эта функция включена, каждый фрагмент в сообщении может быть прочитан до того, как агент его прочитает, поэтому навыки могут применить активный контекст:

Текущая дата:!`date -u +%Y-%m-%d`
Ветка Git:!`git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD`

Эта функция по выключена — любой фрагмент в SKILL.md по умолчанию работает на хосте без одобрения, поэтому включайте ее только для источников функций, которым вы доверяете:

# config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # секунд на фрагмент

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

Протестируйте это

Запустите навыки и убедитесь, что агент правильно следует действовать:

hermes chat --toolsets skills -q "Используй навык X, чтобы сделать Y"

Где следует носить костюмы?

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

• Обработка документов, веб-исследования, рабочие процессы разработки, системное администрирование.
• Регулярно используется в кругу людей.

Если ваш навык является атрибутом и атрибутом, но не является универсальным атрибутом (например, интеграция с платным сервисом, высокая нагрузка), поместите его в optional-skills/ — он связан с репозиторием, доступен для обнаружения через просмотр навыков Hermes (с пометкой "официальный") и настроен с использованием нагрузки.

Если ваши навыки специализированные, созданные сообществом или нишевые, они лучше подходят для Skills Hub — загрузите его в реестр и установите их через hermesskills install.

Навыки публикации

В Центр навыков

hermes skills publish skills/my-skill --to github --repo owner/repo

В пользовательских репозиториях

добавьте ваш репозиторий как нажмите:

hermes skills tap add owner/repo

Затем пользователи могут искать и хранить в вашей репозитории.

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

Все навыки, установленные хаба, передаются через сканер безопасности, который впоследствии:

• Паттерны эксфильтрации данных
• Опыты инновационных промптов
• Деструктивные команды
• Внедрение оболочки-команды

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

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

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