Skills в GigaCode CLI

Что такое skills

Skills — это модульные расширения возможностей агента. Каждый skill представляет собой директорию с обязательным файлом SKILL.md и, при необходимости, дополнительными скриптами, шаблонами и reference-материалами.

Идея skills

Элемент	Назначение
SKILL.md	Основные инструкции для модели
scripts/	Вспомогательные утилиты
templates/	Шаблоны артефактов
Дополнительные .md	Reference, примеры, пояснения

Как skills вызываются

В отличие от слэш-команд, skills по умолчанию вызываются моделью автоматически: агент сам решает, когда использовать skill, опираясь на запрос пользователя и description в самом skill.

Модельный и пользовательский вызов

Тип вызова	Как работает
Model-invoked	Модель сама решает, когда активировать skill
User-invoked	Пользователь вызывает skill явно через /skills

Явный запуск

Если нужно вызвать skill вручную:

/skills <skill-name>

Автодополнение показывает доступные skills и их описания.

Зачем использовать skills

Польза	Что это дает
Расширение рабочих сценариев	Можно добавлять новые типы задач без правки ядра CLI
Переиспользование экспертизы	Один раз оформленные инструкции можно применять снова
Меньше повторяющихся промптов	Частые инструкции выносятся в skill
Совместная работа	Project skills можно шарить через git
Композиция	Можно сочетать несколько skills в сложных задачах

Создание skill

Skills хранятся как директории с файлом SKILL.md.

Personal skills

Personal skills доступны во всех проектах и лежат в:

~/.gigacode/skills/

Создание директории:

mkdir -p ~/.gigacode/skills/my-skill-name

Когда подходят:

• личные workflow;
• экспериментальные skills;
• персональные productivity-хелперы.

Project skills

Project skills лежат внутри проекта:

.gigacode/skills/

Создание директории:

mkdir -p .gigacode/skills/my-skill-name

Когда подходят:

• командные workflow и соглашения;
• проектно-специфичная экспертиза;
• общие утилиты и скрипты.

Project skills можно коммитить в git, и они становятся доступны команде автоматически.

Структура SKILL.md

SKILL.md состоит из YAML frontmatter и Markdown-инструкций.

Базовый шаблон

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
priority: 10
---
 
# Your Skill Name
 
## Instructions
Provide clear, step-by-step guidance for GigaCode CLI.
 
## Examples
Show concrete examples of using this Skill.

Основные поля

Поле	Обязательность	Назначение
name	Да	Имя skill
description	Да	Что делает skill и когда его использовать
priority	Нет	Порядок в списке /skills
Markdown body	Да	Основные инструкции и примеры

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

GigaCode CLI валидирует несколько ключевых полей.

name

name должен быть:

• непустой строкой;
• совместимым с regex /^[\p{L}\p{N}_:.-]+$/u/.

Разрешено:

• unicode-буквы и цифры;
• _;
• :;
• .;
• -.

Запрещено:

• пробелы;
• слеши;
• квадратные скобки;
• прочие потенциально небезопасные структурные символы.

description

description должен быть непустой строкой.

priority

Поведение	Деталь
Поле необязательное	Можно не указывать
Должно быть числом	Только finite number
Большее значение выше	В /skills такие skills показываются раньше
0 по умолчанию	Если поле пропущено или невалидно
Отрицательные значения допустимы	Будут сортироваться ниже обычных

Важно:

• priority влияет только на список /skills;
• autocomplete слэш-команд и /help остаются в алфавитном порядке;
• высокий priority не переставляет встроенные команды.

Рекомендуемые соглашения

Практика	Рекомендация
Naming	Использовать lowercase ASCII и дефисы для shareable names
Description	Описывать и что делает skill, и когда его использовать
Priority	Использовать умеренно, только когда реально важен порядок в /skills

Ограничение по путям: paths:

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

Пример

---
name: tsx-helper
description: React TSX component helper
paths:
  - 'src/**/*.tsx'
  - 'packages/*/src/**/*.tsx'
---

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

Поведение	Деталь
Активация по файловому касанию	Skill не виден модели, пока tool call не затронет matching file
Матчинг glob	Выполняется относительно project root
Вне project root не работает	Внешние файлы активацию не запускают
Активация живет до конца сессии	После первого срабатывания skill остается активным
Сброс	Новая сессия или refreshCache после редактирования skill-файлов

Важные нюансы

• paths: ограничивает только модельное обнаружение skill;
• если не задан user-invocable: false, пользователь все равно может вызвать такой skill через /<skill-name> или /skills;
• ручной слэш-вызов не разблокирует model-side activation;
• если нужно, чтобы модель дальше сама подключила этот skill, сначала должен быть затронут подходящий файл;
• комбинация paths: и disable-model-invocation: true допустима, но путь-гейт фактически теряет смысл, потому что skill скрыт от модели целиком.

Управление видимостью и способом вызова

По умолчанию skill доступен и пользователю, и модели.

user-invocable: false

Если нужно скрыть skill из прямого пользовательского вызова, но оставить его доступным модели:

---
name: model-only-helper
description: Helper the model can call when appropriate
user-invocable: false
---

Эффект:

• skill исчезает из /<skill-name>;
• skill исчезает из picker-а /skills;
• модель по-прежнему может его использовать.

disable-model-invocation: true

Если нужно скрыть skill от модели, но оставить ручной вызов:

---
name: manual-helper
description: Helper you invoke manually
disable-model-invocation: true
---

Эффект:

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

Комбинация полей

Если объединить оба поля:

---
name: hidden-helper
description: Hidden from normal model and user flows
user-invocable: false
disable-model-invocation: true
---

Такой skill не будет доступен ни через обычный user path, ни через model invocation.

Дополнительные файлы skill

Помимо SKILL.md, рядом можно хранить supporting files.

Пример структуры

my-skill/
├── SKILL.md
├── reference.md
├── examples.md
├── scripts/
│   └── helper.py
└── templates/
    └── template.txt

Как использовать внутри SKILL.md

For advanced usage, see [reference.md](reference.md).

python scripts/helper.py input.txt

Где GigaCode CLI ищет skills

GigaCode CLI подхватывает skills из нескольких мест.

Источник	Путь
Personal skills	~/.gigacode/skills/
Project skills	.gigacode/skills/
Extension skills	skills/ внутри установленного extension

Как посмотреть доступные skills

Есть несколько способов.

Через модель

Можно спросить напрямую:

What Skills are available?

Но здесь есть ограничение:

• модель покажет только те skills, которые она сейчас может видеть;
• path-gated skill с paths: не появится, пока не будет затронут matching file;
• skill с user-invocable: false может не показываться пользователю через /skills, но все еще быть доступным модели.

Через слэш-команду

/skills

Этот список показывает user-invocable skills, включая path-gated skills, которые еще не активировались на model side.

Через файловую систему

# List personal Skills
ls ~/.gigacode/skills/
 
# List project Skills
ls .gigacode/skills/
 
# View a specific Skill
cat ~/.gigacode/skills/my-skill/SKILL.md

Как тестировать skill

После создания skill достаточно задать вопрос, который соответствует его description.

Пример:

Can you help me extract text from this PDF?

Если описание skill подходит под задачу, модель должна решить использовать его автоматически.

Отладка skill

Если skill не срабатывает, следует проверить несколько типовых проблем.

1. Сделать description более конкретным

Слишком расплывчато:

description: Helps with documents

Хорошо:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.

2. Проверить путь к файлу

Тип skill	Ожидаемый путь
Personal	~/.gigacode/skills/<skill-name>/SKILL.md
Project	.gigacode/skills/<skill-name>/SKILL.md

Проверка:

# Personal
ls ~/.gigacode/skills/my-skill/SKILL.md
 
# Project
ls .gigacode/skills/my-skill/SKILL.md

3. Проверить YAML-синтаксис

Невалидный YAML мешает загрузить metadata корректно.

cat SKILL.md | head -n 15

Проверьте:

• открывающий --- на первой строке;
• закрывающий --- перед Markdown-контентом;
• отсутствие табов;
• корректные отступы.

4. Посмотреть ошибки загрузки

gigacode --debug

Как делиться skills с командой

Project skills можно распространять через репозиторий.

Типовой workflow

1. Добавить skill в .gigacode/skills/.
2. Закоммитить изменения.
3. Запушить ветку.
4. Остальные участники команды подтягивают изменения.

Пример:

git add .gigacode/skills/
git commit -m "Add team Skill for PDF processing"
git push

Обновление skill

Редактируется напрямую файл SKILL.md.

# Personal Skill
code ~/.gigacode/skills/my-skill/SKILL.md
 
# Project Skill
code .gigacode/skills/my-skill/SKILL.md

Изменения применяются при следующем запуске GigaCode CLI. Если CLI уже открыт, его нужно перезапустить.

Удаление skill

Удаляется вся директория skill.

# Personal
rm -rf ~/.gigacode/skills/my-skill
 
# Project
rm -rf .gigacode/skills/my-skill
git commit -m "Remove unused Skill"

Best practices

Не используйте обобщенные формулировки

Один skill должен решать одну конкретную задачу.

Хорошо	Плохо
PDF form filling	Document processing
Excel analysis	Слишком широкий document skill
Git commit messages	Один skill на много разных несвязанных задач

Пишите понятные описания

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

Пример:

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or .xlsx data.

Проведите тестирование с командой

Перед широким использованием стоит проверить:

• активируется ли skill тогда, когда должен;
• достаточно ли ясны инструкции;
• хватает ли примеров;
• не пропущены ли edge cases.