Гайд · TNWS AI

Как получить JSON-аудит skills в GitHub Copilot CLI

Copilot

13 сентября 2026 6 мин—

Пошаговый JSON-аудит skills через copilot skill list --json: поля name, description, source, path и enabled, фильтрация с jq и CI-проверка.

Этот практический материал показывает, как получить машиночитаемый реестр skills для CI, инвентаризации или сравнения окружений без разбора форматированного текста. Он рассчитан на разработчика, тимлида или инженера платформы, который уже установил GitHub Copilot CLI и хочет управлять skills воспроизводимо. Здесь не рассматриваются тарифы и недокументированные возможности: меняющиеся сведения проверены 13 сентября 2026 года.

Задача и применимость

Skill в Copilot CLI — это каталог с файлом SKILL.md, инструкции которого могут быть добавлены в разговор автоматически или явным вызовом. Поэтому управление skill — не косметическая настройка, а изменение поведения агента. Сценарий полезен, когда нужно получить машиночитаемый реестр skills для CI, инвентаризации или сравнения окружений без разбора форматированного текста. Основная команда материала: copilot skill list --json.

Перед изменением определите область: project, personal, plugin, custom directory или builtin. Одинаковые имена могут скрывать друг друга. Для повторяемой операции всегда фиксируйте текущий рабочий каталог, точное имя, source, path и enabled. Такой снимок позволяет объяснить результат и безопасно откатить решение.

Что подтверждено официальной документацией

По Skills reference GitHub Copilot CLI каждый skill находится в отдельном каталоге с SKILL.md. Frontmatter требует поля name и description; имя содержит только буквы, цифры и дефисы и имеет максимум 64 символа. Дополнительные поля управляют подсказкой аргументов, разрешёнными инструментами и способами вызова.

Раздел про неинтерактивное управление skills документирует copilot skill list [--json], add <source> [--project], remove <name-or-directory>, enable <name> и disable <name>. Важное различие: файл или URL копируется, а переданный каталог регистрируется как custom source. С --project файл или URL копируется в проектную область .github/skills. Проверка актуальности выполнена 13 сентября 2026 года.

Не переносите в production синтаксис из старых публикаций: прежние команды семейства copilot plugins ... --skill обозначены в справке как заменённые. В этом гайде используются только актуальные названия из первоисточника.

Подготовка и безопасная исходная точка

Сначала сохраните инвентаризацию:

pwd
copilot version
copilot skill list --json > skills-before.json
jq empty skills-before.json

Версию стоит записать в журнал запуска, но не связывать статью с конкретным номером: он меняется. jq empty проверяет корректность JSON. Не публикуйте полный файл автоматически, пока не просмотрели поля path: они могут раскрывать локальные имена каталогов. Также не помещайте токены в аргументы, историю shell или SKILL.md.

Если действие затрагивает проект, проверьте корень через git rev-parse --show-toplevel и незакоммиченные изменения через git status --short. Если источник внешний, прочитайте его полностью и закрепите ревизию. Skill способен направлять агента к инструментам, поэтому доверие к инструкции столь же важно, как доверие к скрипту.

Пошаговые действия

Запустите команду из проверяемого репозитория: copilot skill list --json > skills.json.
Проверьте синтаксис командой jq empty skills.json. Пустой вывод и код 0 означают валидный JSON.
Извлеките документированные поля: jq -r '.[] | [.name,.source,.path,.enabled] | @tsv' skills.json.
Для точечной проверки используйте jq -e '.[] | select(.name=="release-check" and .enabled==true)' skills.json. Флаг -e превращает наличие записи в проверяемый код завершения.

После основной операции не ограничивайтесь сообщением терминала. Сделайте второй снимок:

copilot skill list --json > skills-after.json
jq empty skills-after.json
jq -r '.[] | [.name, .source, .path, .enabled] | @tsv' skills-after.json

Сравните точную запись, а не только количество строк. Из-за приоритетов удаление или отключение верхнего источника иногда открывает одноимённый skill ниже. В отчёте должны быть различимы ожидаемое изменение и любой fallback.

Готовый шаблон для копирования

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

set -eu
cd "<КОРЕНЬ_ПРОЕКТА>"

copilot skill list --json > /tmp/skills-before.json
jq -e '.[] | select(.name == "<ИМЯ_SKILL>")' /tmp/skills-before.json || true

: "Основная подтверждённая команда этого сценария"
copilot skill list --json

copilot skill list --json > /tmp/skills-after.json
jq empty /tmp/skills-after.json
jq -r '.[] | select(.name == "<ИМЯ_SKILL>") | {name,source,path,enabled}' /tmp/skills-after.json

|| true допустим только в предварительном поиске, когда отсутствие записи ожидаемо, например перед add. В финальной проверке лучше использовать jq -e без подавления ошибки, чтобы автоматизация не выдала ложный успех.

Реалистичный пример входа и ожидаемого результата

Входная ситуация: Нужно убедиться, что skill release-check обнаружен и включён на агенте сборки, а отчёт сохранить как артефакт.

Действие: инженер выполняет copilot skill list --json, затем получает новый JSON-снимок и сравнивает name, source, path, enabled с исходным состоянием.

Ожидаемый результат: Файл skills.json содержит массив записей. У release-check доступны поля name, description, source, path, enabled; команда jq -e завершается успешно только при enabled: true.

Не считайте точный порядок строк или оформление текстового вывода контрактом. Для автоматической проверки используйте только документированные JSON-поля. Пути сравнивайте осознанно: на разных компьютерах домашний каталог может отличаться, хотя область источника одинакова.

Позитивный и негативный тест

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

jq -e '.[] | select(.name == "release-check")' skills-after.json

Затем выполните негативный тест: запросите заведомо отсутствующее имя и убедитесь, что jq -e возвращает ненулевой код. Для удаления или unregister логика обратная: старый path не должен находиться, но каталог проверяется отдельно, если по условиям он обязан сохраниться.

Функциональный тест выполняйте в отдельном тестовом репозитории. Сначала попросите Copilot сформировать план или выполнить чтение без записи. Сравните поведение с инструкцией SKILL.md, не давая доступ к production-секретам и необратимым операциям.

Типичные ошибки и их диагностика

Первая ошибка — запуск из неверного каталога. Project и inherited skills зависят от расположения. Вторая — путаница между file и directory source: файл копируется, каталог регистрируется. Третья — проверка только по имени без source/path, что скрывает конфликт приоритетов.

Четвёртая ошибка — установка непроверенного URL или каталога. Предварительный просмотр обязателен. Пятая — ожидание недокументированной автоматической синхронизации копии. Если справка не обещает обновление, проверяйте содержимое и устанавливайте новую ревизию контролируемо. Шестая — попытка удалить plugin/builtin skill: для таких источников используйте disable, поскольку remove ограничен добавленными personal/project skills и custom directory registration.

Чек-лист финальной проверки

JSON проходит jq empty.
Каждая используемая запись содержит пять документированных полей.
Фильтр проверяет точное имя.
Секреты и токены не попали в артефакт.
JSON после операции валиден.
Сопоставлены name, source, path и enabled.
Не проявился неожиданный одноимённый fallback.
Токены и чувствительные локальные пути не опубликованы.
Результат и дата проверки записаны в журнале изменений.

FAQ

Какая схема у строки JSON?

Официальная справка указывает поля name, description, source, path, enabled. Не стройте CI на недокументированных полях.

Почему нужен jq -e?

Он возвращает ненулевой код, если фильтр не нашёл подходящую запись, поэтому проверка действительно останавливает job.

Можно ли сравнить два компьютера?

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

JSON включает содержимое SKILL.md?

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

Итог

Команда copilot skill list --json решает узкую задачу только тогда, когда результат проверен по фактическому реестру skills. Надёжный процесс состоит из четырёх частей: снимок до изменения, аудит источника, одна документированная операция и снимок после. Такой подход предотвращает ошибки области видимости, обнаруживает конфликты имён и оставляет понятный след для code review или эксплуатации.