Гайд · TNWS AI

Как зарегистрировать каталог skills в GitHub Copilot CLI

Copilot

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

Регистрация локального каталога как custom skill source через copilot skill add: структура, live-изменения, аудит и отличие от копирования.

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

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

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

Перед изменением определите область: 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 должен находиться в собственном подкаталоге с SKILL.md; прочитайте все новые или изменённые инструкции.
Передайте путь к каталогу команде copilot skill add /opt/company/copilot-skills. Для directory source справка документирует регистрацию, а не копирование.
Получите copilot skill list --json и убедитесь, что ожидаемые имена обнаружены, а path указывает на доверенную коллекцию.
В тестовой копии измените описание одного skill и повторите list. Обновление источника должно читаться из зарегистрированного каталога; это полезно, но требует строгого контроля прав записи.

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

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 /opt/company/copilot-skills

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

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

Входная ситуация: На управляемой рабочей станции каталог /opt/company/copilot-skills обновляется внутренним пакетом и содержит skills incident-summary и release-check.

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

Ожидаемый результат: Обе записи появляются в списке. Файлы остаются в /opt/company/copilot-skills; CLI регистрирует каталог как custom source и не создаёт независимые копии каждого файла.

Не считайте точный порядок строк или оформление текстового вывода контрактом. Для автоматической проверки используйте только документированные 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 в каталоге.
Путь абсолютный и доверенный.
Ожидаемые имена есть в list --json.
Права записи ограничены администраторами источника.
JSON после операции валиден.
Сопоставлены name, source, path и enabled.
Не проявился неожиданный одноимённый fallback.
Токены и чувствительные локальные пути не опубликованы.
Результат и дата проверки записаны в журнале изменений.

FAQ

Чем каталог отличается от файла?

Каталог регистрируется как custom source, а файл или URL копируется в personal/project skills. Это влияет на обновления и удаление.

Можно ли редактировать skill после регистрации?

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

Что при конфликте имён?

Побеждает источник с более высоким приоритетом из официальной таблицы. Проверяйте фактический source через JSON.

Подходит ли сетевой каталог?

Справка допускает directory source, но не гарантирует свойства конкретной сетевой ФС. Проверяйте доступность и модель доверия в своём окружении.

Итог

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