Навыкі агентаў — гэта код: акрэслівайце, раскрывайце, скрыптуйце і тэстуйце

Файл 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 ператварыцца на маленькі внутрашній вікі. Спачатку ў яму 20 ліній, потым хтось дадае крокі развертання, пасля чаго — способы адлучэння проблем, потым — прыклады, а ўжо пазней — опцыі налаштавання. Чэрэз тры месцы агенту трэба чытаць 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.

Гэта лепшая з кількох аспектаў. Скрыпты можна тэставаць на аддзінкі элементы, і ўсё час яны будуць дзейваць аднакова. Ім трэба менш рашэнняў мадэлі, а таксама часта менш вызоў да інструментаў. А калі ўсё пайшло не так, можна воспаўтаваць гэту сітуацыю, не прасіўшы LLM павтарыць свою логіку.

Усё гэта не значыць замены агентаў скрыптамі. Гэта значыць выбір правільнай абстракцыі. Іспользуйце мадэль для прымэткавання, напрыклад, ў выборы тых праектаў, якія можуць падвергнуцца вплыву архітэктурных змян. Іспользуйце код для точных алгорытмаў, напрыклад, для пераказу, якія праекты імпортуюць заданы пакет. Агент коордынуе аба варыянты, і такая комбінацыя лепшая, чым кодаванне цэлага рабочага працэсу на англійскай мове.

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

Інструмент дае агенту дзеянне, тады як навык выучвае, калі і як яго вжываць. Інструмент у командной лініі можа запростаць спосаб для вычыслення падвергнутых вплыву праектаў:

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, доступнасць, безпека і ўсьмо трыццаць іншых тэм, якія мадэль ужо досыць добра розумее.

Лепшым пунктом выходу ёсць власная історыя агента. Неабяжна шукаты парадоксальныя невдачы. Можа, агент:

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

Гэтыя ёсць кандыдаты на навыкі. Жыцёвы цыкл выглядае так: спазіраваць на парадоксальную невдачу, выявіць нехватку процедурных знанняў, запісаць найменшы корыстны навык, перадаць дэтэрміністычныя крокі ў скрыпты, стварыць рэпрэзентатывныя задачы на ацэнку, замерыць, а потым захаваць, паспрабуваць падняць рэвалюацыю навыку або яго удаліць.

Зважайце на пасляпэўны варыянт, кабо ўбачыць, што выдаленне ёсць законным. Навык, які не паслужыць для пакрашчэння поведзення, не ёсць безнэпакойным. Ён даўае дапаможную інфармацыю, падвяшвае трыбуты з адтрывкай і даўае ўсё больш інструкцый, якія могу стаць прычыной суперскупнення пазней.

Праўая абстракцыя — гэта кантролюемы кантэкст

Людзі часта опісваюць навыкі як спосаб расшырэння агентаў. Гэта правда, але гэта маскіруе ўсё цікавейшую інжынерную проблему. Дастаць інфармацыю агенту лёгка, але важкая частка — гэта выбір той інфармацыі, якая будзе рэлевантная пад час конкрэтнай екзекуцыі.

Ояўнеліка агента ёсць не што інша, як вялікі запіты, а скорэ – сістэма працоўных праграм з разнымі слоямі. Усючасна ў яе ёсць загальныя знання модэлю і невялікія глобальныя інструкцыі. Толькі калі задача гэта выкарыстоўвае, прыносзяцца спецыфічныя для задачы навыкі, умовна завантажваныя апавядамленні, дэтэрміністычныя інструменты і кантэкст хранілішча пад час выканання. Кожны слой мае свою задачу. Калі гэтыя адпаведнасці стануць нечыстымі, кантэкст разрастаецца, і становіцца важка зрозумець поведзенне агента. Калі ж іх раздзеліць, навыкі стануць простымі і нечакана нуднымі, што ўсё ж такі добра.

Хорашы навык – гэта не красавіцкі запіт, а компактны фрагмент процедурных знанняў, які прымае дзейснасць у правільных абставінэнтых, выкарыстоўвае дэтэрміністычныя інструменты, калі гэта можліва, і пераканальваецца па асобых параметрах, каб запобiec непаспэкі.