Kodacode 1.0: как работают агентские навыки Koda и зачем они нужны разработчику — VogueTech

Что нового

Kodacode вышел в версии 1.0 и вместе с ней Koda получила полноценную систему агентских навыков (skills). Это переиспользуемые сценарии работы ассистента, которые можно подключать как плагины.

Ключевые изменения:

Появилась единая модель работы с навыками для всех продуктов Koda:
- плагин для VSCode и JetBrains — поддержка навыков с версии 0.7.0;
- koda-cli — поддержка навыков с версии 0.3.0.
Навыки описываются в одном файле SKILL.md с YAML‑метаданными.
Можно ставить навыки глобально (для всех проектов) и локально (внутри конкретного репозитория).
Добавлен служебный навык koda-learn, который помогает… устанавливать другие навыки. Его можно поставить как первый шаг и дальше просить любую модель в Koda сама настроить нужный skill под задачу.
Репозиторий навыков сопровождается автоматически:
- при каждом push в ветку main GitHub Actions запускает генератор;
- обновляется единый файл metadata.json со списком всех навыков, их версиями и ссылками.

Цифр по скорости и качеству ответа новых моделей Koda в релизе нет, но по инфраструктуре вокруг ассистента изменений много: от формата описания навыков до автоматической генерации каталога.

Как это работает

Концепция навыка

Навык — это файл SKILL.md, в котором Koda хранит инструкции для ассистента. Когда запрос пользователя совпадает с описанием навыка, Koda подключает этот файл как инструмент и загружает полные инструкции.

Навык можно вызвать двумя способами:

неявно — когда формулировка задачи подходит под description навыка;
явно — если пользователь прямо просит запустить конкретный skill.

Где лежат навыки

Koda ищет навыки по фиксированным путям:

Для плагина (VSCode / JetBrains):

локально, в проекте:
- .koda/skills/<имя_навыка>/SKILL.md

Для CLI:

локально, в проекте:
- .kodacli/skills/<имя_навыка>/SKILL.md

Общий вариант для всех продуктов Koda:

локально, в проекте:
- .agents/skills/<имя_навыка>/SKILL.md

Глобальная и локальная установка

Глобальные навыки живут в домашней директории пользователя:

Linux / macOS: ~/ или $HOME
Windows: %USERPROFILE%

Пример глобального пути:

%USERPROFILE%\.agents\skills\koda-learn\SKILL.md

Локальная установка — это та же структура, но в корне конкретного проекта. Такой навык виден только внутри этого репозитория.

Формат SKILL.md

В начале файла — YAML‑фронтматтер с метаданными навыка:

---
name: skill-name # Идентификатор (kebab-case, 1-64 символов)
description: Описание # Когда срабатывает и что делает (1-1024 символов)
metadata:
  author: koda
  version: "1.0.0"
---

Требования к полю name:

допустимы только строчные буквы, цифры и дефисы;
длина от 1 до 64 символов;
нельзя использовать заглавные буквы;
нельзя начинать с дефиса;
нельзя ставить двойной дефис внутри имени.

Примеры:

✅ корректно: code-review, sprint-planner, github-flow
❌ некорректно: Code-Review (есть заглавные), -my-skill (дефис в начале), my--skill (двойной дефис)

Автообслуживание репозитория навыков

Koda хранит каталог навыков в файле metadata.json. Его не нужно обновлять вручную:

при каждом push в ветку main срабатывает workflow .github/workflows/generator.yml;
запускается скрипт генерации metadata.json;
если есть изменения, GitHub Actions делает коммит с сообщением вида:
- Update metadata 2024-01-01T00:00:00Z.

Структура metadata.json:

{
  "skills": [
    {
      "name": "skill-name",
      "description": "Описание навыка",
      "version": "1.0.0",
      "url": {
        "web": "Ссылка на файл SKILL.md для просмотра в браузере",
        "raw": "Ссылка на сырой файл SKILL.md для установки"
      }
    }
  ],
  "count": 8,
  "lastUpdate": "2024-01-01T00:00:00Z"
}

Подробная схема описана в ./metadata-schema.json в репозитории.

Что это значит для вас

Для кого это вообще нужно

Система навыков адресована тем, кто активно использует Koda как ассистента в разработке:

разработчики, которые хотят стандартизировать типовые задачи: ревью кода, генерация тестов, миграции;
команды, которым важно, чтобы ассистент действовал по единым правилам в разных IDE и CLI;
мейнтейнеры проектов, которые хотят положить в репозиторий «правильный» способ общения с ассистентом.

Где навыки реально помогают

Повторяемые сценарии.

Например, у вас есть свой формат ревью или чек‑лист по безопасности. Вы описываете его в SKILL.md, и дальше любой разработчик в команде может вызывать этот навык по имени.
Ограничение контекста.

Навык живёт в проекте. Koda не лезет за его пределы в файловой системе, поэтому можно уверенно хранить локальные инструкции именно рядом с кодом.
Единые настройки в разных инструментах.

Один и тот же навык работает в плагине Koda для VSCode/JetBrains и в koda-cli. Не нужно дублировать настройки.
Автоматическая установка через ассистента.

После установки koda-learn вы можете просто сформулировать задачу, а ассистент сам предложит поставить нужный skill в директорию проекта.

Где ожидания будут лишними

Навыки не увеличивают контекст моделей Koda и не ускоряют сами ответы. Они только структурируют инструкции.
Это не маркетплейс с графическим интерфейсом. Чтобы подключить skill, нужно работать с файлами и каталогами, а в CLI — с командами.
Если вы редко используете Koda или не готовы поддерживать свои инструкции в кодовой базе, система навыков вряд ли сильно изменит ваш процесс.

Доступность и ограничения

Koda распространяет навыки через GitHub и собственный сайт:

официальный сайт: https://kodacode.ru
загрузка Koda для JetBrains, VSCode и CLI: https://download.kodacode.ru
сообщество в Telegram: @kodacommunity

Для доступа к репозиторию навыков нужен доступ к GitHub. Если он у вас ограничен, придётся настраивать зеркала или скачивать файлы через альтернативные каналы.

Место на рынке

Koda с навыками играет на том же поле, где уже есть кастомные GPT‑профили, промпт‑пресеты и «агенты» в IDE‑плагинах. Но здесь ставка сделана на файловую структуру и GitHub.

Что можно зафиксировать по фактам из релиза:

Навыки Koda — это обычные файлы в репозитории, которые живут рядом с кодом и проходят через Git.
Каталог навыков (metadata.json) собирается автоматически при каждом push в main, без ручного администрирования.
Формат SKILL.md прозрачен и читается как человеком, так и автоматикой.

Прямых сравнений с GPT‑4o, Claude или другими ассистентами в релизе нет. Koda делает упор не на сравнение качества ответов, а на инфраструктуру вокруг ассистента в IDE и CLI.

Если вы уже используете Koda, система навыков — это способ превратить разрозненные подсказки в поддерживаемую «библиотеку сценариев» внутри команды.

Установка

Быстрый старт: навык для установки навыков

Koda предлагает начать с навыка koda-learn, который помогает ставить остальные skills. Пошагово:

Создайте файл в домашней директории.

Linux / macOS:
```
~/.koda/skills/koda-learn/SKILL.md
```
Windows:
```
%USERPROFILE%\.koda\skills\koda-learn\SKILL.md
```
Скопируйте в этот файл содержимое по ссылке из репозитория навыков и сохраните.
Активируйте навык.

В плагине Koda (VSCode / JetBrains):
- включите режим «Агент»;
- откройте панель «Навыки»;
- нажмите кнопку «Обновить список навыков».
В koda-cli:
```
/skill enable koda-learn
```

После этого можно просить любую модель в Koda установить навык под конкретную задачу. Koda положит его в директорию текущего проекта. Ассистент не имеет доступа к файловой системе за пределами проекта, поэтому установка всегда локальная.

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

Общие пути установки

Плагин (VSCode / JetBrains):

.koda/skills/<имя_навыка>/SKILL.md

CLI:

.kodacli/skills/<имя_навыка>/SKILL.md

Для всех продуктов Koda:

.agents/skills/<имя_навыка>/SKILL.md

Глобальная установка:

кладёте директорию навыка (<имя_навыка>) в домашнюю директорию пользователя (~/ или %USERPROFILE%).

Локальная установка:

копируете навык в соответствующую папку в корне проекта.

Как запустить и управлять навыками

Активация в плагинах Koda

В плагинах навыки включены по умолчанию, но список нужно обновить вручную:

Установите или измените файлы навыков.
Откройте панель «Навыки» в режиме «Агент».
Нажмите кнопку обновления списка.
Убедитесь, что нужный навык появился в списке и переключатель напротив стал зелёным.

Активация в koda-cli

В CLI навыки нужно включать вручную.

Если koda ещё не запущен:

koda skills enable <имя_навыка>

Если koda уже запущен:

/skill reload
/skill enable <имя_навыка>

Чтобы проверить список доступных навыков:

/skill list

Если нужного навыка нет в списке, обновите его:

/skill reload

Инструменты для работы с репозиторием навыков

В репозитории есть Makefile для обслуживания генератора метаданных.

Доступные команды:

make help — показать справку по командам;
make install — подготовить виртуальное окружение генератора;
make metadata — запустить генерацию metadata.json;
make clean — удалить виртуальное окружение генератора.

Лицензия

Все файлы в репозитории навыков распространяются по лицензии MIT. Это позволяет свободно использовать, модифицировать и встраивать навыки Koda в свои проекты, в том числе коммерческие.