Проєктування, вдосконалення та підтримка навичок агентів у Perplexity

Продукти-агенти передової лінії Perplexity базуються на фундаменті ноу-хау та предметної експертизи, упакованих у модульні Agent Skills. Ми підтримуємо ретельно відібрану бібліотеку навичок у наших технічних середовищах. Ці навички включають багато утиліт загального призначення, що забезпечують роботу Perplexity Computer; можливості для конкретних вертикалей, таких як фінанси, право та охорона здоров'я; а також дуже довгий «хвіст» із модулів для задоволення потреб користувачів. Деякі навички викликаються нечасто, але є критично важливими коли викликаються. Щоб забезпечити незмінно чудовий користувацький досвід, команда агентів Perplexity приділяє якості навичок стільки ж уваги, скільки й якості коду.

Інтуїція та найкращі практики, необхідні для розробки високоякісної навички, суттєво відрізняються від тих, що потрібні для створення традиційного програмного забезпечення. Команда агентів переглядає безліч запитів на витягування (pull requests) від чудових інженерів, які розробляють навички в ході своєї роботи. Результатом майже завжди є численні коментарі та пропозиції щодо доопрацювання. Це пояснюється тим, що багато корисних патернів для написання коду стають антипатернами під час створення навичок.

Наприклад, якщо взяти деякі афоризми з PEP20 – Zen of Python, швидко стає зрозуміло, що написання хорошого коду Python не схоже на написання хороших навичок. З 20 рядків мудрості принаймні половина є повністю хибними або активно вводять в оману під час написання навичок. Ось п'ять із них:

П’ять контрастів між «Дзеном Python» і рекомендаціями статті щодо написання Skills.

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

Що таке навичка?

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

Навичка складається щонайменше з чотирьох речей, особливо в контексті того, як ми їх створюємо в Perplexity.

Навичка — це директорія

Навичка — це не просто один файл SKILL.md. У багатьох випадках навичка містить кілька файлів. У директорії, названій на честь вашої навички, ви можете мати:

SKILL.md: frontmatter та інструкції

scripts/: код, який агент виконує, а не вигадує наново

references/: важка документація, що завантажується за потреби

assets/: шаблони, схеми та дані

config.json: налаштування користувача під час першого запуску

Цей патерн «зірка» дозволяє тримати навички дуже сфокусованими та компактними, а структуру папок можна використовувати дуже креативно. Іноді особливо складні навички виграють від кількох рівнів ієрархії, щоб допомогти моделі орієнтуватися краще. Припустимо, навичка вимагає знань у 300 темах, які можна згрупувати у 20 предметних областей. Надійний вибір правильної теми серед 300 є невирішеним завданням навіть для найкращих сучасних передових моделей. Для моделі набагато простіше зосередитися на одній із 20 областей, ніж на 15 темах усередині цієї області.

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

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

Розгорнути

Навичка — це формат

Навичка — це формат. Основний кореневий файл SKILL.md повинен мати як назву, так і опис. Крім того, навичка повинна точно відповідати назві директорії, в якій вона розташована. Назва повинна складатися з символів у нижньому регістрі, не мати пробілів і може використовувати дефіси. Опис є тригером маршрутизації. Це поширена точка збою: опис — це не внутрішня документація про те, що робить навичка. Це інструкції для моделі щодо того, коли завантажувати навичку. Отже, ви часто бачитимете «Завантажувати, коли», а не «Ця навичка робить». Це важливо через те, як більшість реалізацій впроваджують опис у контекст моделі.

У межах frontmatter також є «depends:», що дозволяє створювати ієрархічні залежності навичок, та «metadata:», який використовується для оглядів та оцінок. Різні системи агентів можуть навіть визначати власні поля frontmatter для використання у спосіб, характерний для цих систем. Як альтернатива, метадані, специфічні для навички, можуть бути упаковані в допоміжний файл конфігурації JSON або YAML. Це бажано під час створення систем агентів, яким необхідно забезпечувати різні типи поведінки під час виконання для кожної навички, не забруднюючи контекст моделі дрібницями. Нарешті, подібної поведінки можна досягти шляхом видалення frontmatter навички під час читання. Computer використовує цю методологію, яка дозволяє зберігати конфігурацію в кореневому файлі SKILL.md. У логіці синтаксичного аналізу потрібна пильна увага до деталей, і ви можете захотіти реалізувати умовне видалення, якщо є певні поля, які корисно мати в контексті моделі.

Навичка є виклика́ною

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

Існує принаймні три рівні витрат контексту в тому, як ми реалізували навички в Computer. Ось цей процес:

Computer викликає load_skill(name="...")

Computer копіює директорію навички в ізольовану пісочницу виконання

Computer рекурсивно автоматично завантажує залежності у тегу «depends:»

Потім Computer видаляє frontmatter, і таким чином агент бачить лише основну частину та додаткові файли

Різні системи агентів можуть вибирати різні способи надання доступу до вмісту навички. Наприклад, деякі системи можуть взагалі не виставляти файлову ієрархію, залишаючи моделі можливість самостійно виявити ієрархію за допомогою операцій з файловою системою. Інші системи можуть надати моделі мапу всього дерева файлів до певного обмеження скорочення та/або глибини. Щоб підтримувати чистоту контексту, Computer опускає повні ієрархії файлів з контексту виклику; однак це можна перевизначити для кожної навички окремо.

Навичка є прогресивною

Навички є прогресивними. У Computer є три різні рівні витрат контексту, і ми маємо всі три на різних етапах:

Три рівні контексту Skill: індекс, повне завантаження Skill і файли довідки під час виконання.

Computer створює індекс навичок, який містить назву та опис для кожної доступної навички. Бюджет для цього становить близько 100 токенів на навичку (коротше — ще краще). Це так жорстко обмежено, оскільки ви сплачуєте цю вартість у кожному сеансі для кожного користувача. Це впроваджується в системний запит на самому початку розмови. Модель має доступ до низки назв навичок і описів, щоб вона могла вирішити, чи викликати «load_skill()». Вимоги для потрапляння в цей індекс надзвичайно високі. Ваша навичка повинна бути дуже корисною, а опис повинен бути надзвичайно щільним і лаконічним, оскільки всі сплачують цю вартість весь час.

Після того, як система агентів завантажує навичку, з'являється повний тіло-файл SKILL.md. В ідеалі основний текст не повинен перевищувати 5000 токенів. Навіть у цьому випадку ви хочете, щоб кожен рядок мав значення, тому що як тільки ви завантажуєте навичку, решта розмови повинна сплачувати цю вартість, поки ви не досягнете межі стиснення. Багато тредів завантажують від трьох до п'яти різних навичок, помножуючи цю вартість. Навички з великою кількістю зайвого тексту майже напевно погіршать інші навички, а також загальні можливості агентів. Коротше кажучи, якщо ваша навичка завантажується і не робить правильних речей — це змарнований контекст.

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

В індексі кожен токен важливий. Завантажене тіло навички є більш вільним, а час виконання — найвільнішим. Це може бути 20 000 токенів або нуль токенів. Це той рівень, на якому ви можете подумати про розширення контексту моделі у прогресивний спосіб.

Коли вам потрібна навичка?

Команду агентів часто запитують, чи дійсно потрібна навичка для певного домену чи сценарію використання. Вкрай рідко у нас є остаточна відповідь лише на основі первинних принципів. Єдиний спосіб дійсно це з'ясувати — почати з вашого агента без навички, запустити кілька ключових запитів, а потім з'ясувати, чи добре справляється агент.

Коли вам потрібна навичка

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

Можливо, ваші знання є довговічними, але відсутні в даних навчання. Можуть існувати обмеження або робочі процеси, специфічні для підприємства, або це може бути справою смаку. Наприклад, у нас є кілька пов'язаних із дизайном навичок у Computer, написаних Генрі Модісеттом (нашим керівником відділу дизайну). Причина існування кожного токена в цих навичках полягає в тому, що Генрі має дуже гарний смак щодо дизайну вебсайтів і PDF-файлів. Генрі вказує, які шрифти використовувати, а які ні, як ці шрифти відчуваються, та інші питання судження, які модель не може засвоїти лише з навчальних даних.

Коли вам не потрібна навичка

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

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

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

Кожна навичка — це податок

Ось корисний тест, який ви можете застосувати до кожного речення у своїй навичці: «Чи зробив би агент цю помилку без цієї інструкції?» Якщо речення не повинно там бути, воно не може дозволити собі бути там, тому що кожен сплачує цю вартість щоразу. Коли ви вирішуєте, чи варто додавати навичку, пам'ятайте про цей податок, коли кожен сеанс і кожен користувач коштують токенів.

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

« Je n’ai fait celle-ci plus longue que parce que je n’ai pas eu le loisir de la faire plus courte. » — Blaise Pascal, Lettres Provinciales, 1657

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

Якщо ви помічаєте, що намагаєтеся створити навичку з першої спроби та виставити PR (pull requests) за п'ять хвилин, результати майже напевно будуть нижчими за середні. Насправді ранні дослідження показали, що якщо ви використовуєте LLM для написання навичок, LLM, імовірно, не отримає від цього користі: «Самостійно згенеровані навички не приносять жодної користі в середньому, що показує, що моделі не можуть надійно створювати процедурні знання, від споживання яких вони виграють».

Як створити навичку

Іншими словами, вам потрібно впровадити свою думку в будь-яку навичку, яку ви пишете. Виконайте такі кроки.

Крок 0: Напишіть оцінки (Evals)

Спочатку напишіть деякі оцінки. Ви можете отримати тестові випадки з:

Реальні запити користувачів: вибірка з production або вашого кола довіри

Відомі збої: Агент зазнав невдачі через те, що навичка не існувала

Плутанина з сусідами: Близько до межі вашого домену, але спрямовується до іншої навички

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

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

Крок 1: Опис

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

Знову ж таки, поганий опис описує те, що робить навичка або чому вона корисна. Хороший опис говорить про те, коли агент повинен завантажити навичку. Наприклад, скажімо, у вас є щось для моніторингу запитів на витягування (PR). Не пишіть, що робить навичка. Напишіть те, що кажуть інженери, коли вони розчаровані і хочуть, щоб ви переконалися, що їхній PR працює, наприклад «наглядати», «стежити за CI» або «переконатися, що це впроваджено».

Ось короткий чек-лист:

Починається з «Завантажувати, коли...»

Орієнтир — 50 слів або менше

Описує намір користувача, в ідеалі з реальних запитів

Не узагальнює робочий процес

Реальні запити — це те, що ви можете охопити за принципом 80-20. Зазвичай добре працюють два-три приклади. Додати точно й тільки стільки, скільки потрібно — нелегко.

Крок 2: Написання тіла

Далі напишіть вміст самої навички. Зверніть увагу, що це не крок 0 і не крок 1.

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

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

Наприклад, вам не потрібно писати: «git log # знайти коміт; git checkout main; git checkout -b <clean-branch>; git cherry-pick <commit>;»

Натомість напишіть: «Зробіть cherry-pick коміту на чисту гілку. Вирішіть конфлікти, зберігаючи первинний намір. Якщо він не може бути чисто впроваджений, поясніть чому».

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

Далі зосередьтеся на підводних каменях або негативних прикладах. Це контент із надзвичайно високою точністю, оскільки він часто спрямовує модель щодо того, чого не слід робити. Якщо ви додаватимете рядок щоразу, коли агент спотикається, ви навчатиметеся під час запуску, і підводні камені зростатимуть органічно.

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

Крок 3: Використання ієрархії

Використовуйте ієрархію навичок, коли у вас є скрипт, посилання або ви використовуєте якийсь конкретний інструмент:

Рекомендовані варіанти використання скриптів, довідкових матеріалів, ресурсів і конфігурації в межах Skill.

Для всього, що є умовним або розгалужується від основної навички, винесіть це в окрему папку. Також пам'ятайте, що багаторівневу ієрархію можна використовувати для особливо складних навичок. Для них вам потрібно ретельно подумати про те, чи повинна функціональність бути реалізована монолітно, чи як набір навичок (можливо, з відносинами завантаження на основі depends:).

Крок 4: Ітерація

Далі зробіть низку ітерацій на гілці. Почніть на головній гілці без навички, зробіть кілька ітерацій, створіть набір основних запитів та запустіть серію оцінок. Будь-хто, хто переглядатиме ваш код навички, подякує вам за подання єдиного набору змін із комплектом для оцінювання. Перегляд послідовних інкрементальних змін (окрім нового підводного каменю) є дуже складним, тому намагайтеся мінімізувати це.

Ви, ймовірно, зробите багато дрібних змін слів. Невеликі зміни слів в описах можуть мати надзвичайно великий вплив на маршрутизацію (включно з побічними ефектами на інші навички), тому виконайте всю цю роботу перед кроком 5.

Крок 5: Випуск

Випускайте.

Як підтримувати навичку

Тепер, коли ви написали навичку, її потрібно підтримувати.

Маховик підводних каменів

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

Навички переважно доступні лише для доповнення. Розділ підводних каменів накопичує найбільшу цінність з часом:

Агент робить помилку в чомусь → Додати підводний камінь

Агент завантажує навичку не за призначенням → Уточнити опис і додати негативні оцінки

Агент не завантажує навичку тоді, коли повинен → Додати ключові слова та позитивні оцінки

Зміни системного запиту → Перевірити на наявність конфліктів або дублювання

Легко помітити окремий випадок збою у внутрішньому тестуванні або у виробництві та додати підводний камінь. Це негативний приклад, тому він не дуже змінює явні вказівки, але повідомляє моделі: «Гей, є ось такий відомий збій».

Переходячи від принципу 80-20 до досягнення рівня успішності 99,9% або 99,99%, легко розширювати цей список підводних каменів. Побачивши ці негативні приклади, ви повинні переважно дописувати їх до розділу підводних каменів. Вам не слід додавати довші інструкції чи змінювати опис.

Набори оцінок (Eval Suites)

У Perplexity ми запускаємо безліч наборів оцінок для перевірки різних речей. Існують завантаження навичок та читання файлів навичок, які перевіряють точність, повноту (recall) та заборонені перевірки самого завантаження навичок. Чи буде агент спрямовувати вашу навичку тоді, коли це необхідно? Це гарантує, що нові навички не порушують існуючі межі.

Існують також оцінки, які можуть перевіряти правильність прогресивного завантаження. Агент може завантажити навичку, але чи читає він додатковий файл або файли? Наприклад, якщо у вас є фінансова навичка для фінансових запитів, чи читає вона спеціальний файл FORMATTING.md?

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

Нарешті, важливо запускати ці оцінки проти різних моделей. Computer підтримує принаймні три різні сімейства моделей оркестрації: GPT, Claude Opus та Claude Sonnet. Ви хочете запустити завантаження навичок та доменні навички проти цих різних оркестраторів агентів, щоб переконатися, що ви не отримуєте різну поведінку. Sonnet і GPT поводяться зовсім по-різному, коли справа стосується навичок.

Останні думки та висновки

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

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

Чи можете ви автоматизувати розбір інцидентів (postmortems)? Чи можете ви переглядати запити на витягування (pull requests)? Для будь-якого завдання, яке ви можете виконати, ви можете принаймні зробити первинний прохід за допомогою навички агента. Це заощадить вам значний час.

Тим не менш, пам'ятайте, що навичка — це не легко і не завжди необхідно. Менше — краще. Кілька інших висновків:

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

Опис — це найскладніша частина. «Завантажувати, коли...» (кожен слово коштує уваги).

Підводні камені — це контент надзвичайно високої цінності. Починайте з малого, розширюйтеся в міру помилок агента.

Пам'ятайте, що легко зламати інші вже існуючі навички, додавши нову навичку, навіть якщо ви її не торкалися (остерігайтеся віддаленої дії).

Використовуйте всі доступні інструменти щоразу, коли ви пишете та підтримуєте навичку. Якщо ви хочете дізнатися більше, вебсайт Agent Skills містить багато хороших прикладів, і як наш внутрішній репозиторій, так і публічна екосистема містять чимало прикладів добре спроєктованих навичок.

Цитування

@online{perplexity2026DesigningRefiningAndMaintainingAgentSkillsAtPerplexity,
  author = {{Perplexity} and Marshall Kiely and Daisy Lee and Jerry Ma and Lauren Kolm},
  title = {{Designing, refining, and maintaining agent skills at Perplexity}},
  date = {2026-05-01},
  url = {https://www.perplexity.ai/hub/blog/designing-refining-and-maintaining-agent-skills-at-perplexity}
}