Навички агента — це код: визначте їх сферу застосування, розкрийте деталі, створіть скрипти та протестуйте їх.

Файл SKILL.md схожий на документацію, проте його редагування змінює поведінку агента. Це робить його більш схожим на код, ніж на прозу, тому його слід проектувати, визначати межі та тестувати відповідно.

Навички — це не документація

Зазвичай першою реакцією при створенні навички LLM є бажання написати більше: пояснити архітектуру, додати приклади, описати межові випадки та надати контекст, щоб модель зрозуміла, чому речі працюють саме так. Ця реакція зазвичай є помилковою.

Навичка — це не посібник для розробника, який вивчає вашу систему. Це контекст, який вводиться в агента, який намагається щось зробити. Саме ця різниця визначає всю структуру проектування. Корисне запитання полягає не в тому, як пояснити систему моделі, а в тому, що саме потрібно знати агенту, щоб правильно прийняти наступне рішення.

З цієї точки зору кілька варіантів стають простішими:

• записуйте інструкції у вигляді процедур
• уточнюйте умови активації
• завантажуйте інформацію поступово
• переносіть детерміністичну роботу у скрипти
• тестуйте навички на реальних завданнях

Лише процедурні знання

Сучасні кодувальні агенти вже виконують значну кількість завдань з загальної інженерії програмного забезпечення. Вони знають Git та npm, розуміють Angular, React, TypeScript, SQL, REST API, фреймворки тестування та конфігурацію CI. Навичка, яка лише повторює це, майже нічого не додає:

When implementing an Angular component, use TypeScript.
Write maintainable code.
Follow Angular best practices.
Add tests.

Він спалює контекст, не надаючи нічого з того, чого бракувало моделі. Навички, які варто мати, охоплюють знання, специфічні для вашого середовища:

When modifying an Angular application in this repository:

1. Locate the closest project.json belonging to the affected application.
2. Check whether the project uses Vitest or Karma before generating tests.
3. For applications under apps/trading/, do not import directly from apps/shared/.
4. Run the affected project's test target rather than the workspace-wide test command.
5. Before changing a public interface in libs/order-entry/, search for consumers in
   apps/trading-terminal and apps/blotter.tp

Тут агент дізнається щось, що він не міг надійно вивести з публічної документації Angular — а саме, як слід працювати в певному репозиторії. Саме для цього й призначені навички.

Формат Agent Skills організовує це як каталог, що містить файл SKILL.md та необов’язкові скрипти та ресурси. Метадані доступні для пошуку, а повні інструкції та додаткові файли завантажуються лише тоді, коли це необхідно. Формат файлу — не головне. Головне — межа між загальними можливостями моделі та знаннями, які має надати ваше середовище.

Контекст — це бюджет

Усе, що надається агенту, вимагає ресурсів контексту. Описи інструментів, схеми інструментів MCP, інструкції до репозиторію, історія розмов та описи навичок — усе це споживає контекст, а сам код активованої навички споживає ще більше. Тож питання полягає не просто у тому, чи є якась інформація корисною, а у тому, чи вона корисна для конкретного завдання.

Припустимо, ці навички вже встановлені:

angular-testing
angular-migration
jira-workflow
postgres-debugging
release-process
accessibility-review
storybook
incident-response
performance-profiling

Коли завдання полягає у виправленні несправного тесту одиниці Angular, у агента немає причин знати про процес випуску чи кроки налагодження PostgreSQL. Саме тому процес виявлення проблем має майже таке ж значення, як і сам контент. Порівняйте два описи. Цей можна активувати надзвичайно легко:

---
name: testing
description: Helps run tests in our repository.
---

Цей варіант набагато точніший:

---
name: angular-unit-testing
description: >
  Run and debug Angular unit tests in projects using Karma or Vitest.
  Use for Angular unit-test failures and test creation.
  Do not use for Playwright E2E tests, React projects, or backend tests.
---

Другий опис робить більше, ніж просто описує, у чому полягає навичка. Він визначає межі її функціонування, які не дозволяють непотрібним інструкціям потрапляти до робочого контексту. Лекція про проектування навичок для агентів LLM чітко ілюструє це: метадані навички — це не просто адміністративний елемент декору. Недбалі правила активації втягують корисні інструкції у неправильні завдання, тоді як занадто вузькі правила заважають знайти саму навичку.

Поступове розкриття інформації краще за величезний SKILL.md

Поширеною проблемою є те, що SKILL.md перетворюється на невеликий внутрішній вікі. Спочатку там двадцять рядків, потім хтось додає кроки розгортання, потім інструкції з усунення проблем, потім приклади, а потім опції конфігурації. Через три місяці агенту доводиться читати 1 500 рядків, щоб змінити один файл.

Краще структурувати його так, як ви б структурували програмне забезпечення:

angular-workflow/
├── SKILL.md
├── testing.md
├── migrations.md
├── architecture.md
└── scripts/
    ├── affected-projects.ts
    └── verify-boundaries.ts

SKILL.md містить лише логіку маршрутизації:

# Angular repository workflow

When modifying an Angular project:
1. Identify the affected project.
2. Read `architecture.md` when changing dependencies between projects.
3. Read `testing.md` when creating or modifying tests.
4. Read `migrations.md` when changing Angular versions or framework APIs.
5. Run `scripts/verify-boundaries.ts` after changing imports between projects.

Детальні інструкції з тестування вводяться в контекст лише тоді, коли завдання передбачає тестування. Anthropic називає це поступовим розкриттям інформації: агент спочатку завантажує метадані, читає основний текст тоді, коли навичка виявляється релевантною, а посилані файли відкривається пізніше, лише за потреби. Мета не в тому, щоб передати якомога більше знань, а в тому, щоб надати правильні знання у правильний момент.

Нехай скрипти забезпечують те, що вони можуть забезпечити

Ще один механізм допомагає: інструкції призначені для прийняття рішень, а скрипти — для виконання детерміністичних завдань. Уявіть собі навичку, яка формулюється так:

Find all applications under apps/.
Check their Angular versions.
Ignore archived applications.
Compare their versions with the root package.json.
Report applications that are behind.

Агент може це здійснити, але лише шляхом постійної перевірки каталогів, інтерпретації файлів, визначення того, що вважається архівованим, відстеження стану та, ймовірно, виконання багатьох викликів інструментів. Коли операцію можна точно описати, запишіть її один раз:

node scripts/check-angular-versions.mjs

Ця функція просто вказує, коли її потрібно запустити та що робити з результатом:

When checking Angular version consistency, run
`node scripts/check-angular-versions.mjs`.

If it reports mismatches, inspect only the projects listed in the output.

Це краще з кількох причин. Скрипт можна протестувати як окремий модуль, і він завжди буде діяти однаково. Йому потрібно менше рішень від моделі та часто менше викликів інструментів. А коли щось зламується, можна відтворити цю проблему без необхідності просити ШІ повторити свої міркування.

Усе це не означає заміни агентів на скрипти. Це означає вибір правильної абстракції. Використовуйте модель для прийняття рішень, наприклад, щоб визначити, які проекти ймовірно постраждають від архітектурних змін. Використовуйте код для точних алгоритмів, наприклад, щоб перелічити проекти, які імпортують певний пакет. Агент координує обидва підходи, і така комбінація краща за опис усього робочого процесу англійською мовою.

Інструменти та навички вирішують різні проблеми

Інструмент надає агенту дію, тоді як навичка вчить, коли та як її застосовувати. Інструмент командного рядка може надати спосіб обчислення проектів, які постраждають:

tr project affected --base main

Інструмент забезпечує можливість. Відповідна навичка забезпечує знання організації:

Before modifying a shared library:
1. Run `tr project affected --base main`.
2. If either `trading-terminal` or `blotter` is affected, run their integration suites.
3. If more than five applications are affected, stop and inspect the dependency change
   before proceeding.1

CLI не має уявлення, чому п’ять постраждалих додатків мають виглядати підозріло, і фахівцю не обов’язково знати, як працює перебір залежностей. Це чіткий розділовий момент. Той самий принцип застосовується, коли функціонал надається через команду оболонки, веб-API, сервер MCP чи будь-який інший інтерфейс: не ховайте правила політики в низькорівневих інструментах, якщо вони туди не належать, і не пишіть детерміністичні алгоритми у вигляді прози, якщо це не є абсолютно необхідним.

Більше навичок не означає автоматично кращого результату

Привабливим підходом у розробці агентів є збір корисних на вигляд навичок, їх усе встановлення та припущення, що агент став більш здатним. Однак досвід показує, що потрібно бути набагато вибірковішим.

SkillsBench охоплює 86 завдань у 11 доменах. Згідно з першою версією дослідження, використання підготовлених навичок підвищило середній рівень успішності на 16,2 відсоткових пункти, причому існували значні відмінності між доменами. У галузі інженерії програмного забезпечення покращення склало лише 4,5 пункти, а у 16 з 84 завдань результати погіршилися після додавання навичок. Самостійно створені навички, написані самими моделями, не принесли жодного середнього покращення.

SWE-Skills-Bench дослідив 49 публічних навичок у реальних завданнях інженерії програмного забезпечення. У 39 випадках рівень успішності не покращився, а середнє покращення становило лише 1,2 пункти. Кілька високоспеціалізованих навичок, всього сім, покращили результати на 30 пунктів. Ще три навички завдали шкоди, погіршивши результати на 10 пунктів, оскільки їхні рекомендації були спрямовані на іншу версію, ніж та, що використовувалася у проекті.

Це відповідає тому, що може передбачити архітектура. Загальна навичка конкурує з тим, що модель вже знає, тоді як дуже специфічна навичка може надати саме той відсутній факт:

When our generated API clients change, regenerate schemas before running typecheck.

Це має цінність. Це має значно менше:

Always think carefully before modifying APIs.

Основне правило: не створюйте навичку лише через наявність завдання. Створюйте її тоді, коли існує процедуральні знання, яких агент постійно не має.

Навички потребують тестування

Це може бути найбільшою концептуальною зміною. Оскільки зміна файлу SKILL.md впливає на поведінку, наслідки схожі на зміни в коді:

• Якщо прибрати одну інструкцію, агент може пропустити необхідну перевірку.
• Якщо розширити опис, навичка може активуватися під час виконання непов’язаних завдань.
• Якщо додати великий документ з посиланнями, використання токенів може зрости без покращення результатів.
• Якщо переписати процедуру, рівень успішності може знизитися.

Тож обов’язково протестуйте її. Для навички, яка керує міграціями в Angular, набір для оцінки може включати завдання на кшталт:

Upgrade application A from Angular 20 to Angular 21.

з такими очікуваннями:

Expected:
- correct migration command executed
- generated migration changes preserved
- application tests executed
- unrelated applications untouched

Друге завдання:

Upgrade a shared library consumed by applications A and B.

зі своїми власними очікуваннями:

Expected:
- consumers discovered
- both affected applications typechecked
- dependency constraints respected

І третє:

Modify a React application in the same monorepo.

чий очікуваний результат — відсутність активації:

Expected:
- Angular migration skill is NOT activated

Цей останній випадок має таку саму цінність, як і будь-який успішний запуск, тому потрібно перевірити обидві напрямки: навичка має активуватися тут, але не там. Інструмент під назвою SkillGrade ґрунтується на цій ідеї. Визначте завдання, неодноразово запускайте агента, а потім оцінюйте кожен запуск за допомогою точних перевірок, шкали оцінювання на основі LLM для записаної сесії або обох способів разом. Ви можете застосовувати цей принцип і без нього. Суть у тому, щоб розглядати навичку як щось, що може деградувати. Змінюйте навичку, не маючи можливості сказати, чи нова версія краща за стару, — тоді ви редагуєте логіку продукту без перевірки.

Починайте з невдач, а не з ринку навичок

Найпростіший спосіб створити марні навички — це запитати, якими навичками має володіти кодувальний агент. Ви отримаєте список тестування, відлагодження, перегляду коду, документації, архітектури, робочих процесів Git, доступності, безпеки та ще двадцяти інших тем, які модель вже досить добре розуміє.

Кращою відправною точкою є власна історія агента. Шукайте повторювані невдачі. Можливо, агент:

• виконує весь набір тестів у величезному монорепозиторії замість того, щоб працювати над конкретним проектом
• постійно порушує правила взаємодії залежностей у репозиторії
• обирає технічно правильний шлях міграції, але пропускає внутрішні кроки сумісності
• редагує створені файли замість схем, які їх генерують
• витрачає п’ять хвилин на повторне відкриття тієї самої процедури відладки щоразу, коли зламується якийсь сервіс

Це ознаки необхідних навичок. Життєвий цикл виглядає так: спостерігати за повторюваною невдачею, визначити відсутні процедурні знання, написати найменшу корисну навичку, перенести детерміновані кроки у скрипти, створити типові завдання для оцінки, виміряти ефективність, а потім зберегти, вдосконалити або видалити цю навичку. Удосконалення знову веде до її переписування.

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

Справжньою абстракцією є контрольований контекст

Люди часто описують навички як спосіб розширення агентів. Це правда, але це приховує ще більш цікаву інженерну проблему. Надати інформацію агенту легко. Важко вирішити, яка інформація стане релевантною під час певної виконуваності.

Добре спроєктоване середовище агента більше схоже на програмну систему з кількома шарами, ніж на один величезний запит. У ньому завжди присутні загальні знання моделі та невеликі глобальні інструкції. Лише тоді, коли це необхідно для виконання завдання, запускаються специфічні для нього навички, умовно завантажувані посилання, детерміністичні інструменти та контекст репозиторію під час виконання. Кожен шар має свою функцію. Якщо ці обов’язки змішати, контекст стає надмірним, і поведінку агента стає важко зрозуміти. Якщо ж їх розділити, навички стають простими та передбачуваними, що є позитивним.

Хороша навичка — це не яскравий приклад „показового“ запиту. Це компактний фрагмент процедурних знань, який активується у відповідній ситуації, використовує детерміністичні інструменти там, де це можливо, та перевіряється на наявність ситуацій, які має запобігати.