VS Code: создание и использование Skill

Этот учебник проведёт вас через создание Agent Skill с нуля и его фактический запуск в VS Code + GitHub Copilot.

Мы создадим Skill для бросания кубика, который научит Agent генерировать случайные числа с помощью команд терминала.


Подготовка

Требования к окружению

В этом руководстве используется VS Code, но Agent Skills — это открытый формат. Тот же навык можно также использовать в совместимых инструментах, таких как Claude Code, OpenCode, OpenAI Codex и т. д.

Для получения дополнительных материалов по VS Code обратитесь к:Учебник по VS Code。


Создайте каталог и файлы навыка

VS Code по умолчанию ищет навыки в.agents/skills/каталоге проекта.

Сначала создайте следующую структуру каталогов в вашем проекте:

Создайте структуру каталогов

# Выполните в корневом каталоге проекта
mkdir -p .agents/skills/roll-dice

Затем создайте следующие файлы в.agents/skills/roll-dice/SKILL.md:

Пример: полное содержимое SKILL.md

---
name: roll-dice
description:Бросайте кости с помощью генератора случайных чисел. Используйте, когда пользователь просит бросить кости (d6, d20 и т. д.) или сгенерировать случайные результаты броска костей.
---

# Метод броска кубика

Используйте следующую команду оболочки, чтобы сгенерировать1случайное число от 1 до указанного числа сторон:

## macOS / Linux

```bash
echo $((RANDOM % <sides> + 1))
```

## Windows PowerShell

```powershell
Get-Random -Minimum 1 -Maximum (<sides> + 1)
```

**Инструкции по использованию:**
Замените `<sides>` на число сторон кубика, указанное пользователем:
-d6: Замените `<sides>` на6
-d20: Замените `<sides>` на20
-Другие числа сторон следуют той же схеме

**Вывод:**Просто верни случайное число результата напрямую, без дополнительных пояснений.

Один файл, менее 20 строк — и полноценный навык готов.


Анализ структуры файла

Давайте разберём назначение этого файла по частям.

Заголовок YAML (Frontmatter)

ПолеНазначениеОписание
nameУникальный идентификатор навыкаДолжен точно совпадать с именем папки, используя строчные буквы и дефисы
descriptionОписание условия срабатыванияСообщает Агенту, когда следует использовать этот навык; это ключевое поле, по которому Агент решает, активировать ли его.

Тело (тело Markdown)

Тело — это инструкции, которым Агент фактически следует после активации навыка.

Здесь мы сообщаем Агенту: когда пользователь просит бросить кубики, используй команду генерации случайных чисел операционной системы и передай в команду количество граней кубика.

Мы также предоставляем команды для платформ macOS/Linux и Windows, а Агент автоматически выберет их в зависимости от текущей среды.


Проверьте свой навык

После создания файла проверьте его, выполнив следующие шаги:

  1. Откройте свой проект в VS Code

  2. Откройте панель Copilot Chat (сочетание клавиш Ctrl+Shift+I или Cmd+Shift+I) или нажмите кнопку в правом верхнем углу:

  3. В нижней части панели чата выберитеAgent-режим
  4. Введите команду/skillsи убедитесь, что roll-dice отображается в списке навыков

  5. Вы можете видеть, что список навыков содержит roll-dice:

Если вы не видите roll-dice в списке /skills, проверьте, правильно ли указан путь к файлу:.agents/skills/roll-dice/SKILL.md, учтите, что SKILL.md должен быть в верхнем регистре.

После того как вы убедитесь, что навык загружен, введите в чате следующее:

Roll a d20

Агент должен автоматически активировать навык roll-dice, выполнить команду в терминале и вернуть случайное число от 1 до 20.


Как это работает изнутри

Когда вы используете этот навык в Copilot Chat, под капотом происходят три шага:

Шаг 1: Обнаружение

Когда сессия чата начинается, Агент сканирует каталог навыков по умолчанию (.agents/skills/) и находит roll-dice.

Он читает только имя и описание и узнаёт, что "этот навык предназначен для бросания кубиков."

Шаг 2: Активация

Когда вы вводите "Бросьте d20", Агент сопоставляет ваш вопрос с описанием roll-dice.

После успешного сопоставления Агент загружает полное содержимое SKILL.md в контекст.

Шаг 3: Выполнение

Агент следует инструкциям в теле, распознаёт, что вы используете macOS (или Linux), и выбирает команду bash.

Он подставляет 20, соответствующее d20, в команду и выполняетecho $((RANDOM % 20 + 1)), затем возвращает вам результат.


Общие советы по устранению неполадок

ПроблемаВозможная причинаРешение
/skills list пустПуть к файлу SKILL.md указан неверноУбедитесь, что файл находится в каталоге проекта .agents/skills/roll-dice/
Агент не выполнил командуРазличия в надёжности вызова инструментов у моделейПопробуйте переключить модель или скажите более явно: "помоги мне бросить d20"
Не удалось выполнить командуРазличия в среде командной оболочкиУбедитесь, что команда $RANDOM корректно выполняется в терминале macOS/Linux

Советы по использованию в разных инструментах

Хотя в этом руководстве используется VS Code, навык также можно использовать в других инструментах:

ИнструментРасположение хранилища навыков
VS Code + Copilot.agents/skills/ или .github/copilot/
Claude Code.claude/skills/ или ~/.claude/skills/
OpenAI Codex.codex/skills/

Разные инструменты могут использовать разные каталоги по умолчанию, но сам формат Skill и структура файлов универсальны.

Другие расширения