Навык — это переиспользуемая процедура для конкретной задачи. В отличие от правила ([Правила](/docs/rules)), которое действует постоянно, навык подгружается моделью только когда он релевантен текущему запросу — остальное время он не занимает контекст. ## Что такое скилл Скилл — это папка с файлом `SKILL.md` внутри. Имя папки одновременно служит именем скилла: только строчные латинские буквы, цифры и дефисы, без дефиса в начале и конце и без двух дефисов подряд, до 64 символов. `SKILL.md` описывает, когда и как агенту использовать эту процедуру — по спецификации [Agent Skills](https://agentskills.io), открытого стандарта, который используют разные агентские инструменты. Помимо самого `SKILL.md`, скилл может включать дополнительные файлы, которые агент подгружает по мере необходимости: ```text .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 ```markdown --- 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`», это работа для [правила](/docs/rules), а не для скилла. ## Как агент выбирает скилл В каждый запрос попадают только имя, описание и путь к файлу каждого доступного скилла — не его содержимое. Модель сопоставляет описания с задачей и, если что-то подходит, читает `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` и в `/`-списке не показывается. ## Просмотр и управление скиллами Список найденных скиллов открывается командой **Настроить навыки…** (в меню настройки чата пункт называется **Навыки чата**). Оттуда можно открыть любой скилл на редактирование, создать новый или удалить существующий — удаление убирает всю папку скилла, а не только `SKILL.md`. ## Создание скилла Три способа, от самого быстрого: - **`/create-skill` в чате** — опишите процедуру словами, и агент соберёт `SKILL.md` за вас. Если вы только что прошли эту процедуру вместе с ним вручную, он предложит обобщить её из истории диалога. То же самое делает команда **Создать навык**. - **Команда «Новый файл навыка…»** — спрашивает каталог и имя (с проверкой на допустимые символы), создаёт папку и заготовку `SKILL.md` с заполненным фронтматтером. - **Руками** — просто заведите папку с `SKILL.md` по одному из путей выше. Пока файл открыт в редакторе, WorkAI подсвечивает ошибки фронтматтера: неизвестные поля, неверное имя, расхождение имени с папкой, превышение лимитов. ## Что делать, если скилл не подхватился Сначала проверьте самое частое: - папка скилла лежит прямо в каталоге скиллов, а не на уровень глубже, и содержит `SKILL.md`; - имя в `name` совпадает с именем папки — при расхождении скилл известен агенту под именем папки, а не под тем, которое вы ждёте; - есть непустой `description` — без него скилл виден только через `/`; - не стоит `disable-model-invocation: true`, если вы ждёте, что агент подберёт скилл сам; - скиллы не выключены целиком настройкой **Use Agent skills**, а нужный каталог не отключён в `chat.agentSkillsLocations`. Если внешне всё в порядке, посмотрите, что именно увидел агент: команда **Открыть логи отладки агента** открывает журнал. Событие **Skill Discovery** показывает, сколько скиллов нашлось и загрузилось, что было пропущено (например, повтор имени или ошибка разбора файла) и какие каталоги вообще просматривались. Событие **Resolve Customizations** показывает, что из найденного дошло до модели, а что отсеялось — с причиной: нет описания, автоподбор запрещён. Разобраться в журнале можно и не читая его самому: попросите агента воспользоваться встроенным скиллом `troubleshoot` — он для этого и сделан. ## Правила и навыки — в чём разница - **Rules** — требования, которые вы задаёте сами. Персональные правила применяются везде, проектные — только в текущем проекте. - **Skills** — переиспользуемая процедура для конкретной задачи. В отличие от правила, скилл подгружается только когда он релевантен запросу. То есть правило — это постоянно действующий контекст («всегда пиши тесты на Jest»), а скилл — процедура, которую агент достаёт с полки под конкретную задачу («как задеплоить этот сервис»).