Skills

Общее описание

Концепция Навыков заимствована из подходов Anthropic.

Навыки основаны на инструментах, с которыми может работать агент (tools, в том числе MCP-tools), и инструкциях применения этих инструментов Skills.md. За счет того, что в Skills.md присутствует короткая Meta-информация по навыку, контекст для LLM не переполняется.

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

на кухне есть множество кастрюль, сковородок, ножей, ложек и т.п. ← аналог tools, которые использует ИИ-агент;
если вы решили приготовить какое-то блюдо, вам надо вспомнить все кухонные инструменты и придумать, в какой последовательности их использовать. Что усложняет процесс приготовления;
вы можете взять книгу рецептов. ← аналог Навыков (Skills);
в книге рецептов есть оглавление с кратким описанием каждого рецепта. Теперь вам предстоит быстро найти нужный рецепт, внутри которого будет инструкция по приготовлению блюда. Что упрощает процесс приготовления.

Что такое навык

Навык — это оформленный набор инструкций, контекста и логики, который помогает GigaCode выполнять конкретную задачу.

Навык = инструкция + контекст + структура выполнения.

Когда навыки особенно полезны

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

Преимущества использования навыков

повторяемость: один раз настроили — используете сколько угодно раз;
консистентность: результаты становятся одинаково качественными;
экономия времени: не нужно каждый раз заново писать инструкции;
масштабируемость: навыки можно передавать другим людям или использовать в команде.

Когда стоит создавать навык

вы делаете одну и ту же задачу больше 2–3 раз;
у задачи есть понятные шаги;
результат должен соответствовать определенному стандарту;
вы хотите делегировать задачу ИИ.

Когда навык не нужен

задача разовая;
нет понятного процесса;
каждый раз требуется полностью уникальный подход.

Основы

Из чего состоит навык

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

SKILL.md — основной файл навыка с YAML frontmatter и инструкциями в Markdown;
scripts/ — исполняемый код (Python, Bash и т. д.);
references/ — документация, которая подгружается по мере необходимости;
assets/ — шаблоны, шрифты, иконки и другие ресурсы.

Ключевые принципы проектирования

Постепенное раскрытие информации

Навыки используют три уровня: YAML frontmatter для быстрого распознавания, основной текст SKILL.md для полных инструкций и дополнительные файлы для детальных справок.

Компонуемость

ИИ-агент может загружать несколько навыков одновременно, поэтому каждый навык должен корректно работать рядом с другими.

Переносимость

Один и тот же навык можно использовать в GigaCode plugin, GigaCode CLI при наличии нужных зависимостей.

Навыки и MCP

MCP — это инфраструктура доступа к инструментам и данным, а навыки — это рецепты и рабочие методики, объясняющие, как использовать эти инструменты наиболее эффективно.

Вместе они позволяют пользователям решать сложные задачи без необходимости вручную описывать каждый шаг workflow.

Планирование и проектирование

Перед реализацией полезно определить 2–3 конкретных сценария использования, которые навык должен поддерживать.

Пример хорошо описанного use case


Сценарий	Планирование спринта проекта
Триггер	Пользователь просит помочь спланировать спринт или создать задачи на спринт
Шаги	1. Получить статус проекта из Sbertrack 2. Проанализировать скорость команды 3. Предложить приоритизацию 4. Создать задачи с корректными метками и оценками
Результат	Полностью спланированный спринт с созданными задачами

Типовые категории навыков

1. Создание документов и артефактов

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

2. Автоматизация workflow

Навык ведет пользователя через многошаговый процесс, используя шаблоны, checkpoints и итерации.

3. Усиление MCP

Навык становится слоем guidance поверх MCP-инструментов и встраивает доменную экспертизу в цепочку вызовов.

Как понять, что навык работает хорошо

навык срабатывает в большинстве релевантных запросов;
workflow выполняется с меньшим числом вызовов инструментов и меньшим расходом токенов;
пользователю не нужно подсказывать модели, что делать дальше;
результаты стабильны от сессии к сессии.

Структура файлов

your-skill-name/
  SKILL.md
  scripts/
  references/
  assets/

Критические правила: файл должен называться ровно SKILL.md, а имя папки навыка должно быть в kebab-case без пробелов.

YAML frontmatter и основные инструкции

Именно по frontmatter ИИ-агент понимает, нужно ли подключать навык в текущем запросе. Если этот блок написан плохо, даже хороший навык может не срабатывать.

Минимально необходимый формат

---
name: your-skill-name
description: Что делает навык. Использовать, когда пользователь просит [конкретные формулировки].
---

Требования к полям

name:

обязателен;
только kebab-case, без пробелов и заглавных букв;
должен совпадать с названием папки.

description:

обязателен;
должен объяснять, что делает навык и когда его использовать;
желательно включать реальные фразы-триггеры;
до 1024 символов;
без XML-тэгов (<or>);
отмечать типы файлов, если актуально.

license:

необязателен;
например: MIT или Apache-2.0.

compatibility:

необязателен;
1–500 символов;
описывает требования к среде, продукту, сети или пакетам.

metadata:

необязателен;
хранит дополнительные пары ключ-значение, например автора, версию или имя MCP-сервера.

Как писать хорошие инструкции в SKILL.md

стройте инструкции по шагам: Шаг 1, Шаг 2 и т. д;
ясно ссылайтесь на приложенные файлы в references/ и assets/;
в основной файл выносите главное, детали — в отдельные документы;
обязательно закладывайте обработку ошибок.

Тестирование и итерации

Навыки можно тестировать вручную в GigaCode CLI или плагине. Практически полезно сначала отточить один сложный, но важный сценарий, а затем расширять покрытие.

Паттерны и troubleshooting

Последовательная оркестрация workflow

Подходит для многошаговых сценариев, где важны строгий порядок, зависимости между шагами и проверки на каждом этапе.

Координация нескольких MCP

Используется, когда workflow затрагивает несколько сервисов, а данные переходят между фазами.

Итеративное улучшение результата

Полезно для отчетов и артефактов, качество которых растет после циклов проверки и доработки.

Контекстно-зависимый выбор инструмента

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

Доменно-специфическая логика

Навык встраивает специализированные правила, например комплаенс, проверку рисков или отраслевые нормы.

Типовые проблемы и решения

Проблема	Причина	Что делать
Навык не загружается	Неверное имя файла или ошибка YAML	Проверьте, что файл называется `SKILL.md` и frontmatter оформлен корректно.
Навык не срабатывает	Слишком общее описание в `description`	Добавьте реальные фразы-триггеры и уточните типы задач.
Навык срабатывает слишком часто	Описание слишком широкое	Сузьте формулировки и укажите отрицательные триггеры.
MCP-вызовы не работают	Проблемы с подключением или правами	Проверьте ключи, scope, OAuth-токены и реальные имена инструментов.
Инструкции игнорируются	Они слишком длинные или неоднозначные	Вынесите критичное вверх, пишите конкретно и добавьте явные проверки.

Ресурсы и финальный чек-лист

Если вы создаете первый навык, начните с best practices и только затем углубляйтесь в API-документацию и примеры репозиториев.

Финальный чек-лист

навык корректно срабатывает на очевидных запросах;
навык корректно ведет себя на перефразированных запросах;
нерелевантные запросы не активируют навык;
функциональные тесты и интеграции проходят без ошибок;
после загрузки навык протестирован в реальных диалогах;
отслеживаются undertriggering и overtriggering, а описание и инструкции улучшаются по обратной связи.

Проводник