Гайд · TNWS AI

Как добавить личный skill из файла в GitHub Copilot CLI

Copilot

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

Практическая установка личного skill из локального SKILL.md через copilot skill add с проверкой копирования, имени и доступности.

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

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

Skill в Copilot CLI — это каталог с файлом SKILL.md, инструкции которого могут быть добавлены в разговор автоматически или явным вызовом. Поэтому управление skill — не косметическая настройка, а изменение поведения агента. Сценарий полезен, когда нужно установить проверенный локальный SKILL.md в персональную область, чтобы он был доступен в разных проектах текущего пользователя. Основная команда материала: copilot skill add ./release-check/SKILL.md.

Перед изменением определите область: 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 способен направлять агента к инструментам, поэтому доверие к инструкции столь же важно, как доверие к скрипту.

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

Создайте отдельный каталог и файл SKILL.md. Перед установкой прочитайте весь файл, особенно frontmatter и инструкции.
Проверьте обязательные поля name и description. Имя допускает буквы, цифры и дефисы и по официальной справке ограничено 64 символами.
Запустите copilot skill add ./release-check/SKILL.md без --project. По умолчанию файл копируется в персональную область skills.
Выполните copilot skill list --json и найдите запись по точному имени. Затем измените исходный временный файл и убедитесь, что установленная копия не изменилась сама: это отличает копирование файла от регистрации каталога.

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

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 add ./release-check/SKILL.md

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 без подавления ошибки, чтобы автоматизация не выдала ложный успех.

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

Входная ситуация: Локальный файл описывает повторяемую проверку релиза и должен работать во всех репозиториях разработчика.

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

Ожидаемый результат: После add skill виден в JSON-списке как персональный и включён. Удаление или изменение исходного ./release-check/SKILL.md не меняет установленную копию.

Не считайте точный порядок строк или оформление текстового вывода контрактом. Для автоматической проверки используйте только документированные 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.

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

Исходный SKILL.md прочитан.
name уникален и валиден.
Команда выполнена без --project.
Запись найдена через list --json.
JSON после операции валиден.
Сопоставлены name, source, path и enabled.
Не проявился неожиданный одноимённый fallback.
Токены и чувствительные локальные пути не опубликованы.
Результат и дата проверки записаны в журнале изменений.

FAQ

Куда устанавливается файл?

Без --project он копируется в персональную область skills текущего пользователя. Точный путь лучше брать из list --json, а не предполагать.

Можно передать каталог вместо файла?

Да, но семантика другая: каталог регистрируется как пользовательский источник и не копируется. Для этого есть отдельный сценарий.

Что проверять перед установкой?

Frontmatter, команды, сетевые обращения и запрашиваемые инструменты. Skill является инструкцией для агента, поэтому источник должен быть доверенным.

Почему изменения исходника не видны?

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

Итог

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