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

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

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

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

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

Создавайте инструмент, когда:

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

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

Встроенные навыки находятся в skills/ и организованы по категориям. Официальные опциональные навыки используют ту же структуру в 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:
  vibeos:
    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: "Текст подсказки для настройки"
    blueprint:                              # Опционально — помечает навык как запускаемую автоматизацию
      schedule: "0 9 * * *"              #   cron-выражение / "every 2h" / ISO-метка времени
      deliver: origin                    #   опционально (по умолчанию origin)
      prompt: "Инструкция задачи для каждого запуска"  # опционально
      no_agent: false                    # опционально
required_environment_variables:          # Опционально — переменные окружения, необходимые навыку
  - name: MY_API_KEY
    prompt: "Введите ваш API-ключ"
    help: "Получить можно на https://example.com"
    required_for: "Доступ к API"
---

# Название навыка

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

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

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

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

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

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

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

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

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

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

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

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

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

Поле	Поведение
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).

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

Каждая запись поддерживает:

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

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

terminal:
  env_passthrough:
    - MY_CUSTOM_VAR
    - ANOTHER_VAR

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

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

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

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

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

Передача в песочницу

Когда ваш навык загружен, любые объявленные 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), настройки конфигурации предназначены для путей, предпочтений и других нечувствительных значений.

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

Каждая запись поддерживает:

• key (обязательно) — dotpath для настройки (например, myplugin.path)
• description (обязательно) — объясняет, что контролирует настройка
• default (опционально) — значение по умолчанию, если пользователь не настроил его
• prompt (опционально) — текст подсказки, показываемый во время vibeos config migrate; если не указан, используется description

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

1. Хранение: Значения записываются в config.yaml по пути skills.config.<key>`:

   skills:
     config:
       myplugin:
         path: ~/my-data

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

3. Внедрение во время выполнения: Когда навык загружается, его значения конфигурации разрешаются и добавляются к сообщению навыка:

   [Конфигурация навыка (из ~/.vibeos/config.yaml):
     myplugin.path = /home/user/my-data
   ]

   Агент видит настроенные значения без необходимости самостоятельно читать config.yaml.

4. Ручная настройка: Пользователи также могут устанавливать значения напрямую:

   vibeos config set skills.config.myplugin.path ~/my-data

Когда что использовать

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

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

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

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

Каждая запись поддерживает:

• path (обязательно) — путь к файлу относительно ~/.vibeos/
• description (опционально) — объясняет, что это за файл и как он создаётся

При загрузке VibeOS проверяет существование этих файлов. Отсутствующие файлы вызывают setup_needed. Существующие файлы автоматически:

• Монтируются в контейнеры Docker как bind-монтирования только для чтения
• Синхронизируются в песочницы Modal (при создании + перед каждой командой, чтобы OAuth работал в рамках сессии)
• Доступны в локальном бэкенде без какой-либо специальной обработки

Когда что использовать

Используйте required_environment_variables для простых API-ключей и токенов (строки, хранящиеся в ~/.vibeos/.env). Используйте required_credential_files для файлов OAuth-токенов, секретов клиента, JSON сервисных аккаунтов, сертификатов или любых учётных данных, которые являются файлом на диске.

Полный пример использования обоих вариантов см. в skills/productivity/google-workspace/SKILL.md.

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

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

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

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

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

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

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

Доставляйте медиа как документы ([[as_document]])

Если ваш навык создаёт скриншот высокого разрешения, диаграмму или любое изображение, где сжатие с потерями в превью навредило бы качеству — добавьте буквальную директиву [[as_document]] где-нибудь в ответе (обычно последней строкой). Шлюз удаляет директиву и доставляет каждый извлечённый медиа-путь из этого ответа как вложение для скачивания, а не как встроенный пузырёк с изображением. Полную семантику см. в разделе Вывод навыка и доставка медиа.

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

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

Токен	Заменяется на
$\{VIBEOS_SKILL_DIR\}	Абсолютный путь к каталогу навыка
$\{VIBEOS_SESSION_ID\}	Идентификатор активной сессии (остаётся на месте, если сессии нет)

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

Для анализа ввода выполните:

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

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

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

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

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

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

# config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # секунд на сниппет

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

Тестируйте

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

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

Где должен находиться навык?

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

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

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

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

Blueprint: навыки, которые также являются автоматизациями

Blueprint — это обычный навык, который дополнительно объявляет расписание в своих метаданных. Добавьте блок metadata.vibeos.blueprint, и навык станет доступной для публикации, запускаемой автоматизацией:

metadata:
  vibeos:
    tags: [blueprint, email]
    blueprint:
      schedule: "0 8 * * *"     # наличие `blueprint:` помечает его как запускаемый
      deliver: telegram          # опционально (по умолчанию: origin)
      prompt: "Суммируй мои непрочитанные письма и сегодняшний календарь."  # опционально
      no_agent: false            # опционально

Поскольку blueprint является навыком, он проходит через весь конвейер навыков без изменений — поиск, проверка, установка, сканирование безопасности, происхождение, taps, централизованный индекс и vibeos skills publish для публикации. Ничего нового учить не нужно.

Установка blueprint. Когда вы устанавливаете навык, содержащий блок blueprint:, VibeOS регистрирует его как предложенную cron-задачу, а не планирует её. Планирование осуществляется по желанию — установка никогда не создаёт молча повторяющуюся задачу. Вы просматриваете и принимаете её через /suggestions:

vibeos skills install owner/morning-brief
# → Blueprint: 'morning-brief' — это автоматизация (расписание 0 8 * * *).
#   Добавлено в ваши предложения — выполните /suggestions, чтобы запланировать или отклонить.

# затем, в сессии:
/suggestions             # список ожидающих предложений, пронумерованы
/suggestions accept 1    # создаёт cron-задачу
/suggestions dismiss 1   # больше никогда не предлагать

Blueprints — это один из источников унифицированной поверхности «Предложенные cron-задачи» — того же места, где появляются курируемые стартовые автоматизации и (в будущем) предложения на основе шаблонов использования и интеграций. См. раздел «Предложенные cron-задачи» ниже.

Публикация созданной вами автоматизации. Blueprint, загруженный cron-задачей (vibeos cron create --skill <name> ...), может быть экспортирован обратно в SKILL.md и опубликован как любой другой навык, так что автоматизация, которую вы настроили для себя, становится устанавливаемой одной командой для кого-то другого.

Уровень blueprint не добавляет новых типов объектов, хранилищ или транспорта — blueprint — это навык, расписание — это cron-задача, а публикация — это существующий путь publish/tap/index.

Предложенные cron-задачи

VibeOS может предлагать автоматизации и позволять вам принимать их одним нажатием, вместо того чтобы заставлять вас собирать cron-задачи вручную. Каждое предложение проходит через один интерфейс — команду /suggestions — независимо от того, откуда оно поступило:

Источник	Триггер
catalog	Курируемые стартовые автоматизации (/suggestions catalog) — ежедневная сводка, монитор важных писем, еженедельный обзор, напоминание о начале рабочего дня
blueprint	Вы установили навык, содержащий блок blueprint:
usage	Фоновый анализ заметил повторяющийся запрос, которому подошло бы расписание
integration	Вы подключили учётную запись (Gmail, GitHub, ...), и предлагаются очевидные автоматизации

/suggestions             # список ожидающих
/suggestions accept N    # запланировать предложение N (создаёт cron-задачу)
/suggestions dismiss N   # отклонить — запоминается, больше не предлагается
/suggestions catalog     # добавить курируемые стартовые автоматизации

Принятие предложения вызывает тот же cron.jobs.create_job, который использует инструмент cronjob — нет второго движка задач. Предложения никогда не создают задачи автоматически; принятие всегда явное. Отклонённые предложения запоминаются по стабильному ключу, чтобы то же самое предложение не предлагалось снова. Список ожидающих ограничен, чтобы он никогда не превращался в стену назойливых напоминаний.

Запись в каталоге монитор важных писем — это паттерн опрос→классификация→представление: она оценивает элементы входящих с помощью дешёвой модели классификатора (auxiliary.monitor в config.yaml) и доставляет только те, что выше порога срочности, оставаясь молчаливой в остальных случаях.

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

В Skills Hub

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

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

Добавьте свой репозиторий как tap:

vibeos skills tap add owner/repo

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

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

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

• Паттерны эксфильтрации данных
• Попытки инъекции в промпт
• Деструктивные команды
• Инъекции shell

Уровни доверия:

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

VibeOS теперь может потреблять сторонние навыки из нескольких внешних моделей обнаружения:

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

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