Скиллы и команды¶

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

Скиллы не раздувают контекст: в подсказку модели попадает только краткий каталог, а полный текст загружается по запросу.

Что такое скилл¶

Скилл описывает процедуру: «как ревьюить API», «как писать миграции», «как проверять релиз».
Основной файл — SKILL.md: заголовок с метаданными и свободный текст инструкции.
Relative-пути внутри скилла (references/, scripts/, assets/) считаются от папки скилла.
Скиллы не добавляют новых инструментов — это инструкции, которые агент применяет уже имеющимися инструментами.

Формат `SKILL.md`¶

Заголовок файла — YAML-метаданные. Обязательны name и description:

Поле	Назначение
`name`	Уникальное имя скилла (латиница, цифры и дефисы); совпадает с именем папки
`description`	Краткое описание — попадает в каталог для модели
`argument-hint`	Подсказка по аргументам в автокомплите `/`
`user-invocable`	`false` — скрыть скилл из `/`-автокомплита
`disable-model-invocation`	`true` — не показывать скилл модели в каталоге
`allowed-tools`	Рекомендуемый список инструментов (носит рекомендательный характер)
`metadata.synth.category`	Категория для группировки в каталоге
`metadata.synth.tags`	Теги для поиска
`metadata.synth.agents` / `groups`	Привязка к агентам или группам агентов
`metadata.synth.mode`	Применимость по режиму: `plan`, `act` или `any`

Где хранятся скиллы¶

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

Источник	Расположение	Кто управляет
Проект	папка `.synth/skills` внутри рабочего каталога проекта	проект
Инстанс (глобально)	общий каталог установки Synth	администратор
Дополнительные каталоги	пути, заданные в конфигурации	пользователь
Совместимые каталоги	`.opencode/skills`, `.claude/skills`, `.agents/skills` и подобные	только чтение
Удалённые каталоги	по URL из конфигурации	только чтение, индексируются

Рекомендуемый порядок для своих скиллов: личные — глобально, командные — в проекте.

Доверие проектным скиллам¶

Каталог скиллов внутри проекта может измениться через git pull, поэтому он проходит проверку доверия:

Скиллы недоверенного проектного каталога видны в реестре и диагностике, но не загружаются: они не попадают ни в каталог для модели, ни в /-автокомплит.
Доверие выдаётся явно для конкретного каталога.
После обновления репозитория содержимое и статус доверия пересчитываются автоматически.

Безопасность

Скилл — это инструкции, которые выполняет агент. Не доверяйте проектным каталогам скиллов из непроверенных источников.

Как включить и отключить¶

Включение скиллов — трёхуровневое, как и у MCP-инструментов:

Уровень	Кто управляет	Что делает
Система	администратор	Мастер-отключение: скилл недоступен нигде, включая старые сессии. Здесь же — что не включать в новых проектах
Проект	владелец проекта	Какие скиллы доступны в проекте и какие включены по умолчанию для новых сессий
Сессия	пользователь	Один тумблер: включить скиллы или отключить их в этой сессии

По умолчанию скилл выключен (opt-in): пока он не включён на нужном уровне, он виден в реестре с причиной, но не активен.
Отключать можно группами (по категории) и отдельными скиллами.
Системное и проектное отключение действует и на старые сессии; смена дефолтов влияет только на новые проекты и сессии.

Прогрессивное раскрытие¶

Скиллы расходуют контекст экономно — в три уровня:

Каталог. В подсказку попадают только имя и краткое описание (плюс пометка, если скилл недоступен). Группируется по категориям.
Тело. Полный SKILL.md загружается по явному /имя от вас или по решению модели через инструмент skill.
Вспомогательные файлы. references/, scripts/, assets/ читаются только по требованию; их список даётся агенту вместе с телом.

Почему не вставлять текст вручную

Вместо копирования инструкции в сообщение используйте /имя — так скилл виден в статистике и доступен всей команде.

Slash-команды¶

Любое сообщение, начинающееся с /, разбирается до обращения к модели. Команды бывают трёх видов:

Вид	Пример	Описание
Встроенные	`/help`, `/skills`, `/commands`, `/summary`, `/init`	Реализованы в Synth
Шаблонные	пользовательские `.md`-файлы	Подстановки `$ARGUMENTS`, `@file`
Скиллы как команды	`/api-review`	Загружает тело соответствующего скилла

Bundles — именованная группа скиллов: /имя-бандла загружает несколько скиллов одним сообщением.
Автокомплит открывается по / и показывает команды с описанием и подсказкой аргументов; недоступные помечаются.
Шаблонные команды берутся из проекта, инстанса и дополнительных каталогов.

Доступность по режимам¶

Скилл можно пометить применимым только к Plan или только к Act.
Если агенту не хватает возможностей (например, нужен shell, которого у read-only агента нет), скилл остаётся видимым, но помечается недоступным с подсказкой делегировать задачу другому агенту.

Права и безопасность¶

У скиллов и команд те же права allow / deny / ask, что и у инструментов, включая паттерны по имени.
Запрет (deny) скрывает скилл из каталога.
Права наследуются саб-агентами.
Встроенный skill-creator помогает создать новый проектный скилл: генерирует SKILL.md и структуру файлов.
Выполнение shell-вставок в шаблонных командах по умолчанию отключено — это потенциально опасный сценарий.