🏠 Главная › Developer Guide › creating skills

sidebar_position: 3 title: "Creating Skills" description: "How to create skills for Hermes Agent — SKILL.md format, guidelines, and publishing" lang: ru

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

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

Это должен быть навык или инструмент?

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

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

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

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

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md              # Required: main instructions
│       └── scripts/              # Optional: helper scripts
│           └── search_arxiv.py
├── productivity/
│   └── ocr-and-documents/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
└── ...

Формат SKILL.md

---
name: my-skill
description: Brief description (shown in skill search results)
version: 1.0.0
author: Your Name
license: MIT
platforms: [macos, linux]          # Optional — restrict to specific OS platforms
                                   #   Valid: macos, linux, windows
                                   #   Omit to load on all platforms (default)
metadata:
  hermes:
    tags: [Category, Subcategory, Keywords]
    related_skills: [other-skill-name]
    requires_toolsets: [web]            # Optional — only show when these toolsets are active
    requires_tools: [web_search]        # Optional — only show when these tools are available
    fallback_for_toolsets: [browser]    # Optional — hide when these toolsets are active
    fallback_for_tools: [browser_navigate]  # Optional — hide when these tools exist
    config:                              # Optional — config.yaml settings the skill needs
      - key: my.setting
        description: "What this setting controls"
        default: "sensible-default"
        prompt: "Display prompt for setup"
required_environment_variables:          # Optional — env vars the skill needs
  - name: MY_API_KEY
    prompt: "Enter your API key"
    help: "Get one at https://example.com"
    required_for: "API access"
---

# Skill Title

Brief intro.

## When to Use
Trigger conditions — when should the agent load this skill?

## Quick Reference
Table of common commands or API calls.

## Procedure
Step-by-step instructions the agent follows.

## Pitfalls
Known failure modes and how to handle them.

## Verification
How the agent confirms it worked.

Навыки, специфичные для платформы

Навыки могут ограничиваться конкретными операционными системами с помощью поля platforms:

platforms: [macos]            # macOS only (e.g., iMessage, Apple Reminders)
platforms: [macos, linux]     # macOS and Linux
platforms: [windows]          # Windows only

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

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

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

metadata:
  hermes:
    requires_toolsets: [web]           # Hide if the web toolset is NOT active
    requires_tools: [web_search]       # Hide if web_search tool is NOT available
    fallback_for_toolsets: [browser]   # Hide if the browser toolset IS active
    fallback_for_tools: [browser_navigate]  # Hide if browser_navigate IS available
Поле Поведение
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, его необходимые переменные автоматически регистрируются для передачи в изолированную среду выполнения (терминал, Execute_code).

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: "Tenor API key"               # Shown when prompting user
    help: "Get your key at https://tenor.com"  # Help text or URL
    required_for: "GIF search functionality"   # What needs this var

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

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

terminal:
  env_passthrough:
    - MY_CUSTOM_VAR
    - ANOTHER_VAR

См. skills/apple/ для примеров навыков только для macOS.

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

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

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor
    required_for: full functionality

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

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

Legacy prerequisites.env_vars по-прежнему поддерживается как псевдоним с обратной совместимостью.

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

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

metadata:
  hermes:
    config:
      - key: myplugin.path
        description: Path to the plugin data directory
        default: "~/myplugin-data"
        prompt: Plugin data directory path
      - key: myplugin.domain
        description: Domain the plugin operates on
        default: ""
        prompt: Plugin domain (e.g., AI/ML research)

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

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

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

  2. Обнаружение: hermes config migrate сканирует все включенные навыки, находит ненастроенные параметры и выводит запрос пользователю. Настройки также отображаются в 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`, отображаются в окне конфигурации).

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

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

required_credential_files:
  - path: google_token.json
    description: Google OAuth2 token (created by setup script)
  - path: google_client_secret.json
    description: Google OAuth2 client credentials

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

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

💡 Tip

Когда какой использовать Используйте `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 может указать агенту запустить встроенный скрипт напрямую с помощью:

To analyse the input, run:

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

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

Встроенные фрагменты оболочки (по желанию)

Навыки также могут встраивать встроенные фрагменты оболочки, записанные как !`cmd` in the SKILL.md body. When enabled, each snippet's stdout is inlined into the message before the agent reads it, so skills can inject dynamic context:

Current date: !`date -u +%Y-%m-%d`
Git branch: !`git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD`

This is off by default — any snippet in a SKILL.md runs on the host without approval, so only enable it for skill sources you trust:

# config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # seconds per snippet

Snippets run with the skill directory as their working directory, and output is capped at 4000 characters. Failures (timeouts, non-zero exits) show up as a short [ошибка встроенной оболочки: ...] marker instead of breaking the whole skill.

Test It

Run the skill and verify the agent follows the instructions correctly:

hermes chat --toolsets skills -q "Use the X skill to do Y"

Where Should the Skill Live?

Bundled skills (in skills/) ship with every Hermes install. They should be broadly useful to most users:

If your skill is official and useful but not universally needed (e.g., a paid service integration, a heavyweight dependency), put it in optional-skills/ — it ships with the repo, is discoverable via hermes install.

Publishing Skills

To the Skills Hub

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

To a Custom Repository

Add your repo as a tap:

hermes skills tap add owner/repo

Users can then search and install from your repository.

Security Scanning

All hub-installed skills go through a security scanner that checks for:

Trust levels: - builtin — ships with Hermes (always trusted) - official — from optional-skills/ in the repo (builtin trust, no third-party warning) - trusted — from openai/skills, anthropics/skills - community — non-dangerous findings can be overridden with --force; dangerous@@IC 0081@@openai/skills/k8s) - skills.sh identifiers (for example skills-sh/vercel-labs/json-render/json-render-react) - well-known endpoints served from /.well-known/skills/index.json

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