Custom agents и agent skills: роли и процедуры команды в репозитории — GitHub Copilot for Senior Developers: Visual Studio 2026, VS Code & CLI

Проверено на: Visual Studio 2026 18.10, VS Code 1.139, Copilot CLI 1.0.89; GitHub Docs и Microsoft Learn по состоянию на 29 сентября 2026 года. Custom agents требуют Visual Studio 18.4+, skills — 18.5+, агенты организации — 18.9+ (Microsoft Learn; в заметках к выпуску они указаны в 18.10).

1. Боль: двенадцать разработчиков, двенадцать личных промптов

В команде ENGAGE в Aldervane пятнадцать разработчиков и одно общее представление о «хорошем ревью». Оно не хранится ни в чьём репозитории. Priya вставляет 40-строчный промпт для ревью из своих заметок, Tomasz набирает «проверь внимательно», а подрядчик на модуле табелей просит «взглянуть по-быстрому». Три ревью одного и того же pull request возвращаются с тремя разными стандартами. Хуже того, у того, кто вставил самый длинный промпт, был включён agent mode — и «ревьюер» тихо исправил два замечания на месте, так что автор их так и не увидел.

Юнит u10 перенёс постоянно действующие соглашения команды в .github/copilot-instructions.md и файлы *.instructions.md для отдельных путей. Это решило задачу «каждый ответ должен следовать нашим правилам именования». Две другие проблемы это не решает:

Роль. «Действуй как наш ревьюер: только чтение, проверь эти пять вещей, отчитайся в таком формате» — это не соглашение для каждого ответа. Это персона, в которую вы переключаетесь, — со своим набором инструментов.
Процедура. «Как мы выгружаем табели в SAP-формат клиента, со скриптом проверки» — это знание, которое агенту нужно лишь изредка. Загружать его в каждый промпт — пустая трата контекста и денег.

Ответ Copilot на первую проблему — custom agent, на вторую — agent skill. И то и другое — Markdown-файлы в репозитории, которые проходят ревью в pull request как код и — с оговорками, которым посвящён этот юнит, — общие для Visual Studio 2026, VS Code, Copilot CLI и cloud agent.

ИллюстрацияA captain hands one orange mission card to three specialised robot crew members, each with its own small toolbox
Описание
A flight-manual style figure (FIG. 11A). On the left, a human captain labelled CAPTAIN holds out a single orange mission card. On the right stand three identical robots labelled REVIEWER, TESTER and PLANNER. In front of each is its own open toolbox with only two or three tools — a magnifying glass for the reviewer, a test tube and a stamp for the tester, a pencil and a ruler for the planner; the first box is labelled TOOLS. The idea: a custom agent is the same model with a different briefing and a deliberately limited toolbox, and the human still owns the mission. The picture does not show how agents are configured or which environment runs them.

2. Карта: четыре способа настройки, по одному вопросу на каждый

Прежде чем разбирать синтаксис, решите, какой механизм вам нужен. Спросите: кто его запускает и когда он загружается?

Механизм	Файл	Кто запускает	Когда попадает в промпт	Для чего
Инструкции репозитория / путей (u10)	`.github/copilot-instructions.md`, `*.instructions.md` с `applyTo`	никто — действуют всегда (или на подходящих файлах)	в каждом запросе	соглашения, которым должен следовать каждый ответ
Prompt-файл	`.github/prompts/*.prompt.md`	разработчик, как `/name`	при вызове	многоразовый шаблон разового запроса
Custom agent	`.github/agents/*.agent.md`	разработчик выбирает его в списке агентов (или его вызывает другой агент)	его тело — на каждом ходе, пока он выбран	роль: персона + набор инструментов + модель
Agent skill	`.github/skills/<name>/SKILL.md` (+ скрипты, справочные файлы)	модель, когда запрос совпадает с `description` skill; или разработчик как `/name`	имя и описание — всегда; тело и файлы — только при активации	процедура со своими ресурсами, нужная изредка

ИллюстрацияDecision tree for choosing between instructions, a custom agent, a skill and a prompt file

Описание

A top-down decision tree with three yes/no questions. First: must every answer follow it? Yes leads to instructions (copilot-instructions.md and *.instructions.md with applyTo). No leads to the second question: is it a role with its own tool limits? Yes leads to a custom agent in .github/agents/*.agent.md, highlighted as the subject of this unit. No leads to the third question: is it a procedure used occasionally, maybe with scripts? Yes leads to an agent skill in .github/skills/<name>/SKILL.md; no — a one-off request template — leads to a prompt file, or a skill with disable-model-invocation.

Замечание о prompt-файлах: VS Code теперь помечает их как устаревшие для новых сессий agent host и рекомендует превращать их в skills с disable-model-invocation: true — это даёт то же поведение «только когда я набираю slash-команду» и к тому же работает в CLI и cloud agent. Существующие prompt-файлы пусть продолжают работать, а новые пишите как skills.

3. Custom agents

Анатомия

Custom agent — это Markdown-файл с YAML front matter. Тело добавляется в начало вашего промпта на каждом ходе, пока агент выбран. Front matter решает, что агент может делать.

Вот версия 1 ревьюера Aldervane в том виде, в каком команда закоммитила её в марте. Прочитайте её до объяснения.

---
name: ENGAGE Reviewer
description: Reviews changes against ENGAGE coding standards and reports findings
tools: ['search', 'usages', 'changes', 'editFiles', 'runInTerminal']
model: Claude Sonnet 5 (copilot)
---
You are the ENGAGE code reviewer. Never modify files.
Check every change for:
1. Client identifiers (engagement codes, client names) in logs or exceptions.
2. Async calls without cancellation tokens.
3. Money as double instead of decimal.
4. Missing tests for public methods.
5. SQL built by string concatenation.
Report findings as a table: file, line, rule, severity, suggested fix.

Дефект — тот самый, на котором обожглась Priya: «Never modify files» — это инструкция, а не разрешение. Список tools выдаёт editFiles и runInTerminal, поэтому модель может — а стараясь быть полезной, иногда и будет — применять собственные предложения. Граница — это список инструментов. Ревьюеру нужны только инструменты чтения:

tools: ['search', 'usages', 'changes', 'problems']

Это общее правило для любого custom agent: минимальные привилегии — во front matter, а не в тексте. Роли, чувствительные к безопасности (ревьюеры, аудиторы, всё, что читает данные клиента), получают инструменты только для чтения.

Front matter в трёх средах

Поле	VS Code	Visual Studio 2026	Copilot CLI
`name`, `description`	да	да (`description` обязателен)	да
`tools`	да; `<mcp-server>/*` — все инструменты сервера; `agent` включает subagents	да; другие имена инструментов (`code_search`, `readfile`, `editfiles`, `find_references`, `runcommandinterminal`)	да
`model`	имя или список по приоритету	да	да
`handoffs`, `agents`, `user-invocable`, `disable-model-invocation`, `target`, `hooks` (preview)	да	не документированы — считайте их только для VS Code	частично; проверьте документацию CLI для своей версии

Где лежат файлы:

Репозиторий: .github/agents/ — читается всеми тремя средами и cloud agent. VS Code также читает .claude/agents/.
Пользователь: ~/.copilot/agents/ (VS Code и CLI); в Visual Studio по умолчанию %USERPROFILE%\.github\agents\ (меняется в Tools > Options > GitHub > Copilot).
Организация: задаются владельцами организации или предприятия на GitHub; обнаруживаются автоматически в VS Code (параметр github.copilot.chat.organizationCustomAgents.enabled) и в Visual Studio 18.9+ (18.10 по заметкам к выпуску).

Ловушка приоритета (CLI): что происходит, если агент с одним и тем же именем есть и в ~/.copilot/agents/, и в .github/agents/? Собственная документация GitHub расходится: страницы how-to по CLI и справочник по плагинам говорят, что побеждает агент из домашнего каталога; справочник команд — что побеждает агент уровня проекта. В любом случае разработчик со старым личным engage-reviewer.agent.md может незаметно запускать собственные правила вместо командных. Не полагайтесь на приоритет: давайте командным агентам имена, которые никто не использует для личных, и перед тем как доверять ревью, проверяйте через /agent, какое определение активно.

Ловушка имён инструментов

Имена инструментов не переносимы. В VS Code инструмент правки называется editFiles, в Visual Studio — editfiles; инструменты поиска различаются полностью. Обе IDE игнорируют нераспознанные имена инструментов — без ошибки. Поэтому ревьюер, настроенный в VS Code и открытый в Visual Studio, может работать не с тем набором инструментов, который задумал автор. Две защиты:

Добавив агента, откройте его в каждой IDE, которой пользуется команда, и проверьте выбор Tools в окне чата.
Для агентов, которые должны вести себя везде одинаково, держите список инструментов минимальным и проверяйте его в той среде, где ставки выше всего.

Использование custom agent

VS Code: выберите его в выпадающем списке агентов в представлении Chat; /agents открывает меню настройки; /create-agent создаёт черновик агента по описанию.
Visual Studio 2026: выберите его в списке агентов Copilot Chat. Для агентов организации перед использованием можно посмотреть определение и организацию-источник — сделайте это.
Copilot CLI: /agent в интерактивной сессии или неинтерактивно: copilot --agent engage-reviewer --prompt "Review the staged changes". CLI может также сам определить агента по его описанию.

4. Handoffs и subagents (VS Code)

В VS Code агентов связывают два механизма. Их легко перепутать, и экзамен их любит.

Handoffs — это кнопки, которые появляются после того, как агент закончил, и предлагают следующий шаг с заранее заполненным промптом. Разработчик остаётся в контуре:

handoffs:
  - label: Start implementation
    agent: engage-implementer
    prompt: Implement the plan above. Run the tests after each step.
    send: false

При send: false промпт только заполняется заранее; разработчик читает план и нажимает отправку. send: true отправляет его автоматически — удобно, и именно на этом шаге исчезает человеческое ревью плана.

Subagents — это другие агенты, которых модель сама вызывает во время задачи. Каждый работает в собственном окне контекста и возвращает только результат. В этом и смысл: планировщик, которому нужно прочитать сорок файлов, может передать чтение исследовательскому subagent и получить сводку на две страницы, вместо того чтобы заполнять свой контекст сорока файлами. Требования: у вызывающего агента в tools есть инструмент agent, разрешённые subagents перечислены в agents (или ['*']), и целевой агент не задаёт disable-model-invocation: true.

	Handoff	Subagent
Кто запускает	разработчик, кнопкой	модель, посреди задачи
Контекст	продолжается в чате	отдельное окно контекста; возвращает результат
Как объявляется	`handoffs:` с `label`, `agent`, `prompt`, `send`	инструмент `agent` + список `agents:`
Цена	без доплат	дополнительные вызовы модели — но основной контекст меньше

5. Agent skills

Анатомия

Skill — это папка. SKILL.md обязателен; всё остальное — по желанию.

.github/skills/
└── engage-timesheet-export/
    ├── SKILL.md
    ├── scripts/validate-export.ps1
    └── references/sap-field-map.md

---
name: engage-timesheet-export
description: Exports ENGAGE timesheets to the client SAP CATS format and validates the file. Use when asked to export, convert or check timesheet data for a client SAP upload.
---
1. Read references/sap-field-map.md for the field mapping.
2. Generate the CSV with the existing TimesheetExporter class; do not write a new exporter.
3. Run scripts/validate-export.ps1 on the output and report every failed row.
4. Never include employee national ID numbers; the mapping marks them as excluded.

Правила, которые validate вам не простит:

name: строчные буквы, цифры и дефисы, не более 64 символов и совпадает с именем папки.
description: не более 1 024 символов. Он должен говорить, что делает skill и когда его использовать, — это единственное, что модель видит, пока skill не активирован.
Visual Studio дополнительно документирует license, compatibility, metadata и allowed-tools; VS Code — argument-hint, user-invocable и disable-model-invocation.

Расположение одинаково в Visual Studio (18.5+) и VS Code: skills проекта — в .github/skills/, .claude/skills/ или .agents/skills/; личные skills — в ~/.copilot/skills/, ~/.claude/skills/ или ~/.agents/skills/. Формат — открытый стандарт Agent Skills (agentskills.io), поэтому та же папка работает и в CLI, и в cloud agent.

Поэтапная загрузка — почему skills дёшевы

ИллюстрацияThree levels of skill loading: discovery, instructions, resources

Описание

A left-to-right chain of three boxes. Level 1, discovery: the name and description of every installed skill are always in context. An arrow labelled 'request matches description, or /name' leads to level 2, instructions: the SKILL.md body, loaded only when the skill is activated (highlighted). An arrow labelled 'step needs the file' leads to level 3, resources: scripts and reference files, loaded only when the body refers to them. The point: twenty installed skills cost twenty short descriptions, not twenty full bodies.

Двадцать skills в репозитории стоят двадцать описаний на запрос, а не двадцать тел. Сравните с custom agent, чьё тело целиком отправляется с каждым ходом, пока он выбран, и с инструкциями репозитория, которые отправляются с каждым запросом каждого разработчика. Длинные знания, нужные изредка, кладите в skills.

Кто может запустить skill

Front matter (VS Code)	`/name` в чате	Модель загружает сама	Для чего
по умолчанию	да	да	большинство skills
`user-invocable: false`	нет	да	фоновые знания, которые разработчик никогда не вызывает напрямую
`disable-model-invocation: true`	да	нет	всё с побочными эффектами: развёртывание, выгрузка данных, массовые правки

В Visual Studio активированные skills отображаются в чате, так что видно, какой из них применяется. Встроенные skills для .NET и Azure поставляются с рабочими нагрузками (18.8+) и по умолчанию выключены: откройте выбор Tools, раскройте Built-in, прочитайте skill (меню ... показывает его папку) и включите только то, что нужно для задачи.

ИллюстрацияA pilot reads one orange manual on his knee while an open flight bag full of closed manuals stands beside his seat
Описание
A flight-manual style figure (FIG. 11B). A pilot sits in the cockpit with one manual open on his knee; it is the only orange object, labelled SKILL, and his finger rests on a page. Beside the seat stands an open flight bag packed with closed manuals, labelled FLIGHT BAG; a third label reads DESCRIPTIONS. The idea: the agent carries the titles and descriptions of all its skills at once, but opens a manual — the SKILL.md body and its scripts — only when the task calls for it. The picture does not show the exact file layout.

6. Цена

Токены и AI Credits. Тело custom agent отправляется на каждом ходе; персона на 3 000 токенов в сессии из 40 ходов — это 120 000 входных токенов ещё до всякого кода. Skills дёшевы, пока не активированы. Subagents добавляют вызовы, но делают основной контекст — и каждый последующий вызов в сессии — меньше. При тарификации по использованию (с июня 2026 года) это бюджетные решения, а не вопрос стиля.

Тихие сбои. Неизвестные имена инструментов игнорируются; skill, у которого name не совпадает с папкой, не загружается; skill с расплывчатым description просто никогда не активируется; личный агент с именем командного затеняет агента из репозитория в CLI. Ни один из этих случаев не выдаёт вам ошибку. Проверяйте каждый новый агент и skill в каждой среде, которой пользуется команда.

Безопасность и цепочка поставок. Skill может содержать скрипты, которые агент запускает в вашем терминале; агент может перечислять MCP-серверы. Относитесь к обоим как к коду: проверяйте их в pull request, держите skills с побочными эффектами за disable-model-invocation: true и никогда не устанавливайте skill сообщества или агента организации, которого вы не прочитали. При работе на клиента папка references/ в skill — ещё одно место, куда могут попасть и закоммититься данные клиента; действуют те же правила, что и для любого файла в репозитории.

Управление. Агенты и инструкции организации (Copilot Business/Enterprise) позволяют практике опубликовать одного ревьюера для всех своих репозиториев. Цена — централизованное владение: кто-то должен его поддерживать, версионировать и отвечать, когда он ошибается.

7. Лабораторная: ревьюер только для чтения и skill выгрузки

Практический путь (для части в IDE достаточно Copilot Free/Pro):

Откройте .github/agents/engage-reviewer.agent.md — шаблон поставляется с исправленной версией только для чтения. Чтобы воспроизвести мартовскую ситуацию, замените строку tools списком из версии 1 выше, выберите агента в VS Code и попросите его исправить первое найденное замечание: убедитесь, что он это может. Затем верните список только для чтения.
В VS Code выберите ENGAGE Reviewer в выпадающем списке агентов, примените и добавьте в индекс подготовленное изменение: git apply samples/patches/u11-ratecalculator-minimum-charge.patch, затем git add src/Engage.Timesheets/RateCalculator.cs — и попросите ревью. Убедитесь, что агент сообщает о поле денег типа double и не предлагает правку.
Откройте тот же репозиторий в Visual Studio 2026, выберите агента и откройте выбор Tools. Запишите, какие из ваших инструментов Visual Studio распознала. Поправьте список так, чтобы у агента был доступ на чтение в обеих IDE.
Создайте .github/skills/engage-timesheet-export/SKILL.md по разделу 5 и скопируйте docs/export/sap-field-map.md в references/, а tools/export/validate-export.ps1 — в scripts/ внутри папки skill. Попросите в agent mode: "Prepare the September timesheet export for the client upload." Проверьте, что чат показывает применение skill.
Добавьте disable-model-invocation: true, повторите тот же запрос, затем явно запустите /engage-timesheet-export. Отметьте разницу.
По желанию (CLI): copilot --agent engage-reviewer --prompt "Review the staged changes"; затем создайте личный ~/.copilot/agents/engage-reviewer.agent.md с другими правилами и посмотрите, какой из них запускается в вашей версии CLI, — потом удалите его. После этого отмените патч: git restore --staged --worktree src/Engage.Timesheets/RateCalculator.cs.

Путь «прочитай и ответь»: если подходящего места у вас нет, пройдите шаги 1–6 на бумаге по файлам из этого юнита и для каждого шага ответьте: что сможет сделать агент, какой файл победит и что вы увидите в чате? Задания ниже проверяют именно эти моменты.

Главное

Инструкции — для каждого ответа; custom agents — это роли; skills — процедуры, нужные изредка; новые prompt-файлы лучше писать как skills.
Разрешения агента — это его список tools. Текст вроде «never modify files» средством контроля не является.
Имена инструментов в Visual Studio и VS Code различаются, а неизвестные имена игнорируются молча — проверяйте в выборе Tools.
Handoff — кнопка для человека; subagent — вызов модели в отдельный контекст.
name у skill совпадает с папкой; description говорит, что и когда; всегда загружается только описание.
Агенты с одинаковыми именами в ~/.copilot/agents/ и .github/agents/ — ловушка: документация CLI расходится в том, какой побеждает, поэтому избегайте совпадения имён и проверяйте через /agent.