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.