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

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

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

Создавайте навык, когда:

• Возможность может быть выражена как инструкции + shell-команды + существующие инструменты

• Она оборачивает внешний CLI или API, который агент может вызывать через terminal или web_extract

• Для неё не требуется собственная интеграция на Python или управление API-ключами внутри агента

• Примеры: поиск по arXiv, git-процессы, управление Docker, обработка PDF, работа с email через 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

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

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

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

Навыки могут объявлять необходимые им переменные окружения. Когда навык загружается через skill_view, его обязательные переменные автоматически регистрируются для передачи в изолированные среды выполнения (terminal, 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 запрашивает их безопасно при загрузке навыка в локальном CLI.

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

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