Skip to main content

Схема файла SKILL.md

Эта страница описывает формат Skills, который читает текущая версия Veai. Общие сведения и создание навыка через интерфейс собраны на странице «Skills (Навыки)».

Где Veai ищет навыки​

Каждый навык находится в отдельном каталоге:

<корень конфигурации>/skills/<имя-навыка>/SKILL.md

Основные корни конфигурации:

  • <корень проекта>/.veai для проектных навыков;
  • ~/.veai для глобальных навыков, доступных во всех проектах;
  • распознанные dot-каталоги других инструментов, например .claude, если в них есть каталог skills.

Veai читает только один уровень каталогов внутри skills. Файл skills/team/refactor/SKILL.md не считается навыком, потому что между skills и SKILL.md находится два каталога.

Минимальный файл​

SKILL.md состоит из YAML front matter и Markdown-инструкции:

---
name: refactor
description: Проверяет план рефакторинга и выполняет его небольшими шагами
---

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

Обязательные поля:

ПолеТипОграничения
nameстрокаОт 1 до 50 символов; допустимы латинские буквы, цифры, _ и -: [A-Za-z0-9_-]{1,50}
descriptionстрокаКратко объясняет агенту, для каких задач нужен навык

name нужен для ручного запуска через /имя-навыка и для разрешения коллизий. Выберите короткое стабильное имя, если навык будут вызывать вручную или на него будут ссылаться из рабочих инструкций. После создания файла введите / в чате и убедитесь, что навык находится по этому имени.

description агент читает при автоматическом выборе навыка. Опишите в нём не только действие, но и ситуацию запуска, например: «Проверяет миграции базы данных перед merge». После сохранения задайте агенту подходящую задачу и проверьте, что он предлагает или вызывает нужный навык. Общие способы создания и запуска навыков описаны на странице «Skills (Навыки)».

Поле schemaVersion необязательно. Если его нет, Veai использует версию v0.1.

schemaVersion: v0.1
name: refactor
description: Проверяет и выполняет рефакторинг

Распознаваемые поля​

Парсер также знает следующие поля. Не рассчитывайте на одно лишь наличие поля: часть из них нужна для совместимости с форматами других инструментов и пока не меняет поведение Veai.

ПолеФормат или состояние в Veai
schemaVersionСтрока; необязательно, значение по умолчанию v0.1
allowed-toolsСтрока или список; читается, но сейчас не ограничивает инструменты навыка
argument-hintПринимается для совместимости, поведение игнорируется
disable-model-invocationПринимается для совместимости, поведение игнорируется
user-invocableПринимается для совместимости, поведение игнорируется
modelПринимается для совместимости, поведение игнорируется
contextПринимается для совместимости, поведение игнорируется
hooksПринимается для совместимости, поведение игнорируется
tagsПринимается для совместимости, поведение игнорируется
contentРаспознаётся парсером, но поведение поля игнорируется; инструкцию пишите в Markdown-теле файла
agentРасширение Veai: режим агента для ручного запуска навыка из каталога или через /имя-навыка
used-byРасширение Veai: список режимов, которым разрешён автоматический вызов навыка

Для переносимого навыка достаточно name, description и Markdown-тела. Не используйте поля без опубликованного поведения для ограничений доступа или других критичных настроек. Доступные действия определяют режим и разрешения инструментов.

Расширения Veai: agent и used-by​

agent: режим для ручного запуска​

Поле agent действует при запуске навыка из каталога или через /имя-навыка в чате.

  • Не указывайте agent, если навык должен запускаться стандартным агентом Code. Это подходит для универсальной короткой процедуры, которой не нужна специализация другого режима.
  • Укажите конкретный режим, если для ручного запуска всегда нужна его специализация. Например, задайте agent: Orchestrator для многошагового сценария: Orchestrator проконтролирует последовательность и подключит специализированных субагентов.

Чтобы проверить настройку, запустите навык через /имя-навыка и убедитесь, что Veai открыл ожидаемый режим.

used-by: автоматический выбор навыка​

Поле used-by управляет только автоматическим выбором навыка агентами. Ручной запуск из каталога или через /имя-навыка остаётся доступным.

  • Не указывайте поле, если навык должен автоматически получать стандартный агент Code. Используйте этот вариант для общей процедуры повседневной разработки.
  • Укажите пустой список used-by: [], если навык должен запускаться только вручную. Это подходит для опасной или дорогой процедуры, которую нельзя выбирать без явной команды пользователя.
  • Перечислите режимы, если автоматический запуск допустим только для них. Например, разрешите Orchestrator и General выбирать многошаговый навык, но не добавляйте режимы с более узкой задачей.

После сохранения проверьте оба пути: задайте подходящую задачу разрешённому агенту, затем вызовите навык вручную через /имя-навыка.

---
name: multi-step-workflow
description: Выполняет многошаговый сценарий с помощью специализированных субагентов
agent: Orchestrator
used-by:
  - Orchestrator
  - General
---

Поля agent и used-by относятся к расширению Veai. Другие инструменты, поддерживающие базовый стандарт Skills, могут их игнорировать. Общие сведения о создании, хранении и запуске навыков смотрите на странице «Skills (Навыки)».

Как разрешаются одинаковые имена​

Если несколько источников содержат навык с одинаковым name, Veai оставляет вариант из источника с более высоким приоритетом. Источники загружаются в таком порядке, от низкого приоритета к высокому:

  1. встроенные навыки;
  2. глобальные навыки из распознанных сторонних dot-каталогов, каталоги сортируются по имени;
  3. глобальные навыки из ~/.veai;
  4. проектные навыки из распознанных сторонних dot-каталогов;
  5. проектные навыки из <проект>/.veai.

Таким образом, проектный навык перекрывает глобальный, а .veai имеет приоритет над другими dot-каталогами в той же области. При коллизии интерфейс не объединяет содержимое двух навыков.

Используйте совпадающий name осознанно, когда для одного проекта нужна локальная версия глобального или встроенного навыка. Скопируйте навык в <проект>/.veai/skills/<каталог>/SKILL.md, сохраните исходное name и измените инструкцию под соглашения репозитория. Затем вызовите /имя-навыка и проверьте, что выполняется проектная версия. В остальных случаях выбирайте уникальные имена, чтобы источник навыка был очевиден.

Ошибки загрузки​

Навык не загружается, если:

  • в SKILL.md нет YAML front matter;
  • YAML содержит синтаксическую ошибку или имеет неверную структуру;
  • отсутствует обязательное поле;
  • значение поля не проходит проверку схемы, например name длиннее 50 символов;
  • файл лежит глубже одного каталога внутри skills.

Veai сообщает путь проблемного поля. Для ошибок YAML и структуры сообщение также может содержать строку и столбец. Откройте группу Error в списке навыков и наведите указатель на ошибку, затем исправьте файл и повторите вызов /имя-навыка.

Связанные страницы​