Настроить Skills в Kilo Code — значит положить папку с файлом SKILL.md в каталог навыков, заполнить frontmatter с полями name и description и убедиться, что агент видит навык. В документации проекта навык описан как папка с инструкциями, которые агент подгружает по совпадению задачи. Ниже — каталоги, готовый SKILL.md, внешние пути, проверка и разбор ошибок.
Механизм: что читается при старте
В документации проекта рабочий цикл навыка разбит на три шага. Сначала идёт обнаружение: при инициализации Kilo Code сканирует заданные каталоги и читает только метаданные — name, description и путь к файлу. Полные инструкции на этом этапе в контекст не попадают. Затем метаданные релевантных навыков включаются в системный промпт активного режима: агент видит список доступных навыков с описаниями. И только потом, когда агент решит, что задача совпадает с описанием, он читает полный SKILL.md и следует инструкциям, при необходимости подгружая связанные файлы или выполняя встроенный код.
Решение о применении принимает сама модель. В документации сказано, что поиск по ключевым словам и семантический поиск здесь не используются: агент оценивает запрос против всех доступных описаний и определяет, подходит ли одно из них однозначно. Отсюда три практических следствия. Формулировка description важна — пишите её так, как пользователи формулируют задачи. Явный вызов работает всегда: фраза «use the api-design skill» запускает навык, потому что агент видит его имя. Размытые описания дают неуверенное совпадение, поэтому указывайте, когда навык применять.
Навыки делятся на общие, доступные во всех режимах, и привязанные к режиму — например, к code или architect. Новая платформа не использует отдельные каталоги под режимы: все навыки попадают в общий пул, а разграничение делается через description во frontmatter. Если навык нужен только в определённых ситуациях, это описывается словами в описании.
Каталоги и приоритет
Навыки загружаются из нескольких мест, что позволяет держать личные и проектные инструкции раздельно. Глобальные навыки лежат в каталоге .kilo в домашней папке: на Mac и Linux это ~/.kilo/skills/, на Windows — \Users\
| Уровень | Путь | Когда применять |
|---|---|---|
| Глобальный | ~/.kilo/skills/ | Личные навыки для всех проектов |
| Проектный | .kilo/skills/ | Соглашения конкретного репозитория |
| Совместимость | ~/.agents/skills/ и .agents/skills/ | Открытый стандарт агентов, загружается по умолчанию |
| Совместимость | ~/.claude/skills/ и .claude/skills/ | Claude Code Compatibility включена |
| Внешний | skills.paths в kilo.jsonc | Общий каталог вне проекта |
| Удалённый | skills.urls в kilo.jsonc | Навыки по URL с манифестом index.json |
При совпадении имён проектные навыки из .kilo/skills/ имеют приоритет над глобальными из ~/.kilo/skills/. Навыки из каталогов совместимости и дополнительных путей загружаются вместе с проектными и глобальными. Каждый загруженный навык доступен и как слэш-команда: меню / показывает навыки отдельной группой Skills. Если имя навыка совпадает с именем кастомной команды или MCP-промпта, команда сохраняет /name, а навык получает вид /name:skill — оба остаются доступны.
Каталог .claude/skills/ подхватывается только при включённой Claude Code Compatibility; без неё этот путь не даёт навыков. Каталог ~/.agents/skills/ относится к открытому стандарту агентов и загружается по умолчанию.
Официальная справка Kilo Code по Skills: https://kilo.ai/docs/customize/skills
Готовый SKILL.md
Файл SKILL.md состоит из YAML-frontmatter и markdown-инструкций. Обязательных полей два. name — до 64 символов, только строчные буквы, цифры и дефисы, без дефиса в начале и конце. description — до 1024 символов, описывает, что навык делает и когда его применять. Необязательные поля: license, compatibility, metadata. Раздел Name Matching Rule требует совпадения name с именем родительского каталога. Ниже в Troubleshooting та же справка противоречит этому требованию. Для переносимого примера используйте одинаковое имя папки и name: так он удовлетворяет более строгому варианту.
Ниже — пример навыка для чек-листа код-ревью. Каталог: ~/.kilo/skills/code-review-checklist/, файл внутри — SKILL.md.
---
name: code-review-checklist
description: Проверка пул-реквеста по чек-листу. Использовать, когда пользователь просит провести код-ревью, проверить диф или оценить изменения перед мержем.
---
# Чек-лист код-ревью
Пройди по изменениям и отметь каждый пункт.
## Границы изменений
- Изменение решает одну задачу.
- Нет посторонних правок форматирования в том же дифе.
## Читаемость
- Имена переменных и функций описывают назначение.
- Нет дублирования логики, которое можно вынести.
## Обработка ошибок
- Внешние вызовы обёрнуты в обработку ошибок.
- Ошибки не проглатываются молча.
## Тесты
- Новое поведение покрыто тестом.
- Тест падает без изменения кода.
## Формат ответа
Верни список: пункт, статус, комментарий со ссылкой на строку.
Дополнительно в каталоге навыка можно держать scripts/ для исполняемого кода, references/ для документации и assets/ для шаблонов. Эти файлы упоминаются в инструкциях, и агент читает их по мере надобности. SKILL.md остаётся единственным обязательным файлом.
Внешние пути и URL
Дополнительные расположения и удалённые URL настраиваются в kilo.jsonc — проектном или глобальном:
{
"skills": {
"paths": ["/path/to/shared/skills", "~/my-skills", "relative/skills"],
"urls": ["https://example.com/.well-known/skills/"]
}
}
Ключ skills.paths принимает абсолютные пути, пути от домашней папки через ~/ и пути относительно корня проекта. Ключ skills.urls принимает адреса удалённых каталогов, отдающих манифест index.json. Путь, начинающийся с / или \ без буквы диска, сначала пробуется как абсолютный; если такого каталога нет, Kilo разрешает его относительно корня проекта, поэтому /.github/skills и .github/skills загружают одни и те же навыки репозитория. Навыки, подхваченные через этот запасной вариант, считаются проектными.
Удалённый сервер отдаёт index.json с массивом skills. В каждом объекте навыка указываются name и files, включающий SKILL.md; version — необязательная строка для обновления кэша. Файлы скачиваются по пути {url}/{skill-name}/{file}. При изменении содержимого или списка файлов удалённого навыка меняйте version: при следующем переобнаружении — по /reload или в новой сессии — Kilo скачает новую версию целиком и атомарно заменит кэш. Если скачивание не удалось, остаётся предыдущая кэшированная версия.
С доверием связаны два правила. Пути, объявленные только в проектном конфиге, остаются недоверенными: их SKILL.md и ссылки вида {file:…} должны лежать внутри проекта, даже если путь абсолютный или начинается с ~/. Внешние файлы не загрузятся с сообщением blocked file reference outside project config scope, и выдача разрешения external_directory доверенным такой путь не делает. Чтобы грузить навыки из-за пределов проекта, объявляйте их skills.paths в пользовательском конфиге, например в ~/.config/kilo/kilo.jsonc.
Как проверить, что навык загружен
Обнаружение навыков происходит при старте сессии. В CLI навыки загружаются при запуске новой сессии или команды kilo run. В расширении VS Code — когда расширение подключается к серверу CLI. Навыки пересканируются в начале каждой новой сессии; чтобы подхватить добавленные или изменённые навыки без перезапуска, используйте /reload.
Проверка идёт в три шага. Первый: выполните /reload или начните новую сессию. Второй: спросите агента напрямую — документация предлагает формулировки «Do you have access to skill X?», «Is the skill called X loaded?», «What skills do you have available?». Ответ агента о загруженности навыка описан как самый надёжный способ проверки после добавления навыка или перезагрузки VS Code. Третий: когда агент применит навык, он вызовет инструмент skill с именем навыка — ищите этот вызов в диалоге; вывод инструмента содержит полный текст навыка, вставленный в контекст.
Если агент подтверждает доступность, навык готов к работе. Если нет — переходите к диагностике ниже.
Навык, правило, инструкция, режим
Четыре механизма Kilo Code решают разные задачи, и путаница между ними — частая причина того, что инструкция «не работает».
| Механизм | Что задаёт | Критерий выбора |
|---|---|---|
| Навык | Папка с SKILL.md, подгружается по совпадению description | Нужна процедура, которая включается под конкретную задачу |
| Правило | Проектные правила, дополняющие навыки | Нужно постоянное ограничение для репозитория |
| Кастомная инструкция | Глобальные инструкции против инструкций на основе навыка | Нужна общая рамка поведения агента |
| Режим | Кастомный режим, использующий конкретные навыки | Нужен набор возможностей под роль, например architect |
Практическое правило: если текст нужен всегда — это правило или инструкция; если он нужен под задачу и может быть объёмным — это навык; если меняется набор инструментов и поведение целиком — это режим. Документация связывает эти механизмы напрямую: кастомные режимы используют конкретные навыки, проектные правила дополняют навыки, а кастомные инструкции сравниваются с инструкциями на основе навыка.
Пять ошибок загрузки
Документация перечисляет частые ошибки и решения.
- «missing required ‘name’ field» — во frontmatter нет поля name. Добавьте name: your-skill-name.
- «name doesn’t match directory» — имя во frontmatter расходится с именем папки. Приведите их к точному совпадению.
- Навык не появляется — неверная структура каталогов. Проверьте, что путь соответствует схеме skills/skill-name/SKILL.md.
- SKILL.md лежит глубже уровня навыка. Файл должен находиться непосредственно внутри каталога навыка, например .kilo/skills/my-skill/SKILL.md, без дополнительной вложенности.
- Ошибка в путях конфига. Если используются skills.paths или skills.urls, проверьте корректность путей и адресов в kilo.jsonc.
Отдельно стоит случай недоверенного внешнего пути: файл не загружается с сообщением blocked file reference outside project config scope. Лечится переносом навыка внутрь проекта или объявлением пути в пользовательском конфиге.
Shell-команды: доверие и выключатель
Тело SKILL.md может содержать shell-команды в синтаксисе !command. Когда агент загружает навык, каждая команда выполняется, а её стандартный вывод заменяет плейсхолдер до того, как содержимое попадёт в модель. Пример из документации — навык repo-status, вставляющий вывод git status —short.
Выполнение ограничено тремя правилами. Команды работают только в навыках из доверенных расположений: глобальные каталоги ~/.kilo/skills/, ~/.agents/skills/ и ~/.claude/skills/, встроенные в Kilo Code навыки и абсолютные пути, объявленные в глобальном конфиге. Проектные навыки из .kilo/skills/ и навыки, полученные по удалённым URL, команды не выполняют — их плейсхолдеры заменяются пометкой о недоверенности. При загрузке доверенного навыка с командами все команды файла перечисляются в одном запросе разрешения до запуска: одобрение запускает их все, отказ прерывает загрузку навыка. Запрос появляется даже при общем автоодобрении bash-команд, а правило запрета на любую из команд всё равно блокирует её.
Выключатель — переменная окружения KILO_DISABLE_SKILL_SHELL: она полностью отключает выполнение встроенных команд. Команды выполняются в каталоге проекта с таймаутом на каждую, вывод обрезается перед вставкой. Плейсхолдеры внутри блоков кода считаются примерами документации и не выполняются, а вывод команд не сканируется повторно на новые плейсхолдеры.
Частые вопросы
Где хранить навык — глобально или в проекте?
Личные навыки для всех проектов кладите в ~/.kilo/skills/, соглашения конкретного репозитория — в .kilo/skills/. При совпадении имён проектный навык имеет приоритет над глобальным. Для переноса личных навыков между проектами документация предлагает каталог ~/.agents/skills/
Почему навык не загружается после добавления?
Проверьте frontmatter: поля name и description обязательны. Убедитесь, что SKILL.md лежит непосредственно в каталоге навыка. Затем выполните /reload или начните новую сессию — навыки пересканируются в начале каждой сессии.
Как убедиться, что агент действительно видит навык?
Спросите агента напрямую: «Do you have access to skill X?» или «What skills do you have available?». Ответ агента о загруженности документация называет самым надёжным способом проверки. Дополнительно ищите в диалоге вызов инструмента skill с именем навыка.
Как подключить навыки из другого каталога или по URL?
Добавьте пути в skills.paths, а адреса — в skills.urls в kilo.jsonc. Пути принимают абсолютные значения, ~/ и относительные от корня проекта; URL должны отдавать манифест index.json. Чтобы грузить навыки из-за пределов проекта, объявляйте пути в пользовательском конфиге.
Выполняются ли shell-команды внутри навыка?
Команды в синтаксисе !command работают только в навыках из доверенных расположений: глобальные каталоги, встроенные навыки и абсолютные пути из глобального конфига. Проектные навыки и навыки по удалённым URL команды не выполняют. Перед запуском появляется запрос разрешения, а переменная KILO_DISABLE_SKILL_SHELL отключает выполнение целиком.