Перейти к содержанию

Навыки агента

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

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

Порядок приоритета от низкого к высокому:

Источник Путь
Встроенные навыки поставляются вместе с CLI
Навыки из расширений <extension>/skills
Пользовательские ~/.kodacli/skills
Пользовательские совместимые ~/.agents/skills
Workspace <рабочая область>/.kodacli/skills
Workspace совместимые <рабочая область>/.agents/skills

Workspace-навыки загружаются только для доверенной рабочей области, если включена trust-механика.

Команды

Интерактивные слеш-команды (полный список — в справочнике команд):

/skills list
/skills enable <name>
/skills disable <name>
/skills reload

Полный список подкоманд:

koda skills list
koda skills install [source] [--path <dir>] [--scope user|project|workspace]
koda skills uninstall <name> [--scope user|project|workspace]
koda skills enable <name> [--scope user|project|workspace]
koda skills disable <name> [--scope user|project|workspace]

Установка

Установить навык можно из трёх источников:

  • Git-репозиторий (https://..., ssh://..., git@..., file://... или путь, оканчивающийся на .git)
  • Локальный каталог с навыком
  • Пакет .skill — zip-архив с навыком внутри

Установка копирует каталог навыка в директорию выбранного scope:

# Из Git-репозитория, глобально для пользователя (по умолчанию)
koda skills install https://github.com/user/my-awesome-skill

# Локальный каталог с навыком в проект
koda skills install ./my-skill --scope project

# Пакет .skill на уровне пользователя
koda skills install ./my-skill.skill

# Подкаталог внутри Git-репозитория, в workspace
koda skills install https://github.com/user/skills-repo.git --path auditor --scope workspace

Scope определяет, куда будет установлен skill:

Scope Куда устанавливается
user ~/.kodacli/skills (по умолчанию)
project <рабочая область>/.kodacli/skills
workspace алиас project, тот же каталог .kodacli

При установке:

  • Каталоги .git и node_modules не копируются
  • Имена устанавливаемых навыков должны быть уникальны (проверяется по name из frontmatter)
  • Повторная установка уже существующего навыка завершится ошибкой — сначала удалите старый

Удаление:

koda skills uninstall my-skill
koda skills uninstall my-skill --scope project

Команды uninstall после удаления каталога также убирают навык из списка отключённых в настройках. Команды enable и disable работают по каноническому имени name из frontmatter, регистр символов не имеет значения.

Отключение

Отключённые навыки сохраняются в настройках (см. skills.disabled):

~/.kodacli/settings.json
{
  "skills": {
    "disabled": ["release-note-writer"]
  }
}

Как агент использует навыки

Загруженный навык попадает в реестр с именем и описанием из frontmatter. Когда модель решает применить навык, она вызывает activate_skill. CLI показывает подтверждение, после чего тело SKILL.md, структура и путь навыка добавляются в контекст.

Навык может ссылаться на локальные scripts/, assets/ и references/. Агент должен читать их по необходимости, а не загружать все сразу.

Жизненный цикл навыка

  1. Обнаружение — при старте сессии CLI сканирует источники и добавляет в системный промпт имя и описание всех включённых навыков.
  2. Активация — когда запрос пользователя подходит под описание навыка, модель вызывает инструмент activate_skill.
  3. Согласие — CLI показывает подтверждение с именем, описанием и структурой каталога, к которому получит доступ агент. Встроенные навыки активируются без подтверждения.
  4. Внедрение — после подтверждения тело SKILL.md, структура каталога и путь добавляются в диалог, а каталог навыка — в разрешённые пути агента.
  5. Выполнение — агент работает, следуя процедурным инструкциям навыка, и может запускать его скрипты через run_shell_command.