Skills

Skills — это переиспользуемая процедура для конкретной задачи. В отличие от правила (Rules), которое действует постоянно, скилл подгружается моделью только когда он релевантен текущему запросу — остальное время он не занимает контекст.

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

Скилл — это папка с файлом SKILL.md внутри. Имя папки одновременно служит именем скилла: только строчные латинские буквы, цифры и дефисы, без дефиса в начале и конце и без двух дефисов подряд, до 64 символов. SKILL.md описывает, когда и как агенту использовать эту процедуру — по спецификации Agent Skills, открытого стандарта, который используют разные агентские инструменты.

Помимо самого SKILL.md, скилл может включать дополнительные файлы, которые агент подгружает по мере необходимости:

.agents/
└── skills/
    └── deploy-app/
        ├── SKILL.md
        ├── scripts/
        │   └── deploy.sh
        ├── references/
        │   └── REFERENCE.md
        └── assets/
            └── config-template.json

Подпапки внутри скилла — обычные файлы рядом с инструкцией: scripts/ для исполняемого кода, references/ для дополнительной документации, assets/ для шаблонов и конфигов. Загружая скилл, агент видит путь к его папке и список файлов в ней (до 50, служебные каталоги вроде node_modules и .git пропускаются) — и читает нужные уже по ходу работы. Такая структура держит основной SKILL.md компактным: детали попадают в контекст только когда действительно нужны.

Формат SKILL.md #

---
name: my-skill
description: Короткое описание того, что делает скилл и когда его использовать.
---

Подробные инструкции для агента.

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

- Используйте этот скилл, когда...

## Инструкции

- Шаги, которые должен выполнить агент
- Специфичные для проекта соглашения

Поля фронтматтера, которые WorkAI понимает:

Поле	Зачем
name	Имя скилла. Должно совпадать с именем папки — иначе редактор подсветит расхождение.
description	Что скилл делает и когда его применять. По нему модель решает, подгружать ли скилл.
argument-hint	Подсказка об ожидаемых аргументах, видна при выборе скилла через /.
user-invocable	false — убрать скилл из списка /-команд, оставив только автоподбор моделью.
disable-model-invocation	true — запретить автоподбор, оставить только явный вызов через /.
context	Значение fork — выполнить скилл отдельным вспомогательным агентом, а не подмешивать инструкции в текущий диалог.
allowed-tools	Инструменты, заранее разрешённые для скилла (строка через пробел по спецификации либо YAML-список).
license, compatibility, metadata	Служебные поля спецификации: лицензия, совместимость с окружениями, произвольные метаданные.

Ключевое поле — description: именно по нему модель решает, релевантен ли скилл текущей задаче, поэтому описание стоит писать конкретно, а не общими словами. Скилл без описания в автоподбор не попадает вовсе.

Длины ограничены спецификацией: description — до 1024 символов, compatibility — до 500. WorkAI проверяет оба лимита и предупреждает, если они превышены, но не блокирует использование — это мягкая проверка на совместимость с другими инструментами, а не жёсткое ограничение.

Полей для привязки скилла к типам файлов (вроде glob-паттернов у правил) в WorkAI нет: скилл либо доступен агенту целиком, либо вызывается вручную. Если нужна привязка «этот контекст — только для *.tsx», это работа для правила, а не для скилла.

Как агент выбирает скилл #

В каждый запрос попадают только имя, описание и путь к файлу каждого доступного скилла — не его содержимое. Модель сопоставляет описания с задачей и, если что-то подходит, читает SKILL.md целиком и дальше действует по нему. Поэтому сотня скиллов в проекте не «съедает» контекст: цена присутствия скилла — одна строчка описания.

Список описаний тоже не безграничен: он ограничен по объёму, и когда скиллов много, у части из них остаётся только имя — агент всё равно может загрузить такой скилл, но выберет его менее охотно. Ещё один довод писать описания коротко и по делу.

Не попадают в этот список: скиллы без description и скиллы с disable-model-invocation: true.

Автоматический и явный вызов #

По умолчанию скилл доступен и для автоматического подбора моделью (по description), и для явного вызова через /. Это поведение сужается двумя полями фронтматтера:

• disable-model-invocation: true — модель не будет сама подбирать этот скилл под задачу; он остаётся доступен только через явный /-вызов. Так скилл превращается в обычную слэш-команду.
• user-invocable: false — обратный случай: скилл убирается из списка /-команд и доступен только автоматическому подбору моделью. В этом случае description обязателен — без него агенту не по чему решать, когда скилл подгружать.

Явный вызов удобен, когда вы точно знаете, какая процедура нужна прямо сейчас. Введите / в чате: над полем ввода появится список, где скиллы собраны в секцию «Навыки», а команды клиента — в секцию «Команды». Дальше можно набирать имя для фильтрации.

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

WorkAI ищет скиллы в нескольких каталогах, чтобы работали и новые скиллы, и те, что вы уже завели для других агентов.

Проектные (действуют только в текущем проекте, ложатся в git и работают у всей команды):

• .agents/skills/
• .github/skills/
• .claude/skills/
• .cursor/skills/

Персональные (действуют во всех ваших проектах):

• ~/.agents/skills/
• ~/.copilot/skills/
• ~/.claude/skills/
• ~/.cursor/skills/

Папка скилла должна лежать непосредственно в каталоге скиллов: список собирается по схеме <каталог>/<имя-скилла>/SKILL.md. Промежуточные папки-категории для группировки не поддерживаются — скилл, спрятанный на уровень глубже, в список не попадёт.

Если один и тот же скилл нашёлся в нескольких местах, побеждает проектный: проектные каталоги имеют приоритет над персональными, а те — над скиллами, которые приносят расширения.

Скиллы можно отключить целиком настройкой Use Agent skills, а отдельные каталоги из списка выше — выключить по одному в настройке chat.agentSkillsLocations. Туда же можно добавить и свой каталог, если он в вашем проекте называется иначе.

Встроенные скиллы #

Часть скиллов поставляется вместе с WorkAI и доступна в любом проекте, без настройки. Основные из них:

Скилл	Что делает
/init	Создаёт или обновляет файлы настройки агента для проекта — AGENTS.md, скиллы, кастомные агенты.
/create-skill	Помогает собрать новый SKILL.md, в том числе вытащив процедуру из уже прошедшего диалога.
/create-instructions	Создаёт файл правила для проектной конвенции.
/create-prompt	Создаёт переиспользуемый промпт-файл для частой задачи.
/create-agent	Создаёт кастомного агента под конкретную роль.
/create-hook	Создаёт хук, который срабатывает на события жизненного цикла агента.
troubleshoot	Разбирается, почему агент повёл себя неожиданно: медленный запрос, пропущенный инструмент, не загрузившиеся правила или скиллы.

Первые шесть вызываются только вручную через / — сами по себе, «под настроение», они не подключаются. Есть и служебные встроенные скиллы, рассчитанные на автоматический подбор: как настроить новый проект с нуля, как установить расширение, как забрать текущие результаты поиска в редакторе, как собрать файлы настройки агента. Последний из них помечен user-invocable: false и в /-списке не показывается.

Просмотр и управление скиллами #

Список найденных скиллов открывается командой Configure Skills… (в меню настройки чата пункт называется Skills). Оттуда можно открыть любой скилл на редактирование, создать новый или удалить существующий — удаление убирает всю папку скилла, а не только SKILL.md.

Создание скилла #

Три способа, от самого быстрого:

• /create-skill в чате — опишите процедуру словами, и агент соберёт SKILL.md за вас. Если вы только что прошли эту процедуру вместе с ним вручную, он предложит обобщить её из истории диалога. То же самое делает команда Generate Skill.
• Команда New Skill File… — спрашивает каталог и имя (с проверкой на допустимые символы), создаёт папку и заготовку SKILL.md с заполненным фронтматтером.
• Руками — просто заведите папку с SKILL.md по одному из путей выше. Пока файл открыт в редакторе, WorkAI подсвечивает ошибки фронтматтера: неизвестные поля, неверное имя, расхождение имени с папкой, превышение лимитов.

Что делать, если скилл не подхватился #

Сначала проверьте самое частое:

• папка скилла лежит прямо в каталоге скиллов, а не на уровень глубже, и содержит SKILL.md;
• имя в name совпадает с именем папки — при расхождении скилл известен агенту под именем папки, а не под тем, которое вы ждёте;
• есть непустой description — без него скилл виден только через /;
• не стоит disable-model-invocation: true, если вы ждёте, что агент подберёт скилл сам;
• скиллы не выключены целиком настройкой Use Agent skills, а нужный каталог не отключён в chat.agentSkillsLocations.

Если внешне всё в порядке, посмотрите, что именно увидел агент: команда Open Agent Debug Logs открывает журнал. Событие Skill Discovery показывает, сколько скиллов нашлось и загрузилось, что было пропущено (например, повтор имени или ошибка разбора файла) и какие каталоги вообще просматривались. Событие Resolve Customizations показывает, что из найденного дошло до модели, а что отсеялось — с причиной: нет описания, автоподбор запрещён.

Разобраться в журнале можно и не читая его самому: попросите агента воспользоваться встроенным скиллом troubleshoot — он для этого и сделан.

Rules и Skills — в чём разница #

• Rules — требования, которые вы задаёте сами. Персональные правила применяются везде, проектные — только в текущем проекте.
• Skills — переиспользуемая процедура для конкретной задачи. В отличие от правила, скилл подгружается только когда он релевантен запросу.

То есть правило — это постоянно действующий контекст («всегда пиши тесты на Jest»), а скилл — процедура, которую агент достаёт с полки под конкретную задачу («как задеплоить этот сервис»).