Проектиране, усъвършенстване и поддържане на агентни умения в Perplexity

Продуктите на Perplexity от тип frontier agent се основават на ноу-хау и експертен опит в съответната област, обединени в модулни Agent Skills. Поддържаме внимателно подбрана библиотека от умения в нашите технически среди. Тези умения включват много от общите помощни програми, захранващи Perplexity Computer; специфични за дадена вертикална област възможности в сфери като финансите, правото и здравеопазването; както и изключително дълга опашка от модули за посрещане на нуждите на потребителите. Някои умения се извикват рядко, но са от критично значение, когато бъдат извикани. За да гарантира стабилно отлично потребителско изживяване, екипът на Perplexity за агенти придава на качеството на уменията също толкова голяма тежест, колкото и на качеството на кода.

Интуицията и най-добрите практики, необходими за разработването на висококачествено умение, се различават значително от тези, изисквани за създаването на традиционен софтуер. Екипът за агенти преглежда много заявки за сливане от отлични инженери, които разработват умения в хода на работата си. Резултатът почти винаги са множество коментари и предложения за редакция. Това е така, защото много полезни модели за писане на код се превръщат в антимодели при създаването на умения.

Например, ако вземете някои от афоризмите от PEP20 – Дзен на Python, бързо става ясно, че писането на добър код на Python е различно от писането на добри умения. От 20-те реда с мъдрост поне половината са напълно погрешни или активно подвеждащи при писането на умения. Ето пет от тях:

Пет контраста между Zen на Python и насоките на статията за писане на умения.

Това ръководство е документът, който инженерите в цяла Perplexity използват при разработването и прегледа на умения. Публикуваме това ръководство и за широката общественост, така че нашите открития и поуки да са от полза за по-общата общност. Независимо дали сте инженер, който проектира производствени умения в ежедневната си работа, потребител на Computer, който иска да разработи собствено умение в област, която познава най-добре, или и двете, това ръководство е за вас.

Какво е умение?

Когато пиете умение, вие не пишете обикновен стар софтуер (въпреки че уменията вече са част от основните логически двигатели за агентни системи). По-скоро изграждате контекст за моделите и техните среди. Едно умение има различни ограничения и различни принципи на проектиране. Ако напишете умение по същия начин, по който пишете код, ще се провалите.

Едно умение представлява най-малко четири неща, особено в контекста на това как ги изграждаме в Perplexity.

Едно умение е директория

Едно умение не е просто един SKILL.md файл. В много случаи дадено умение включва няколко файла. В директорията, кръстена на вашето умение, може да имате:

SKILL.md: входни данни и инструкции

scripts/: код, който агентът изпълнява, а не пресъздава

references/: тежки документи, зареждани условно

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

config.json: първоначална настройка от потребителя

Този модел със звезда и спици ви позволява да поддържате уменията много фокусирани и стегнати, като структурата на папката може да се използва по изключително творчески начин. Понякога особено сложните умения се възползват от много нива на йерархия, за да помогнат на модела да се ориентира по-добре. Да предположим, че дадено умение изисква познания по 300 теми, които могат да бъдат групирани в 20 предметни области. Надеждният избор на правилната тема сред 300 е нерешен проблем дори за най-добрите съвременни модели. За модела е много по-лесен проблем за избор да се насочи към една от 20 области, отколкото сред 15-те теми в рамките на тази област.

Като пример за това как многостепенната йерархия носи стойност, нашият екип приложи три нива на тематично влагане в уменията, захранващи възможностите на Computer за данък върху доходите на физическите лица в САЩ през изминалия данъчен сезон. Тази йерархия бе абсолютно незаменима предвид сложността на данъчното законодателство: в нашите ранни тестове представянето на модела на една единствена папка, съдържаща всички 1945 раздела от Данъчния кодекс на САЩ, доведе до по-лоша производителност, отколкото ако умението изобщо не бе заредено. Организирането на информацията в логически подразделения бе незаменимо за осигуряването на операции за четене с висока прецизност.

И все пак тази йерархия не дойде безплатно. Нарастващите нива на йерархия изискват нарастващи нива на кураторство в информационната архитектура за управление на получената индиректност. Създадохме бързи справочни ръководства, персонализирани помощни програми за търсене и други инструменти, които да поддържат модела при локализирането на информация с минимална индиректност. В този случай извършването на тежката работа по кураторството в крайна сметка доведе до положителен краен резултат: умение, което позволи на моделите да изпълняват задачи, свързани с данъците, много по-компетентно, отколкото само с помощта на общи инструменти.

Уголеми

Едно умение е формат

Едно умение е формат. Основният файлов корен SKILL.md трябва да има както име, така и описание. Освен това умението трябва точно да съответства на името на директорията, в която се намира. Името трябва да бъде изцяло с малки букви, да няма интервали и може да използва тирета. Описанието е задействащият механизъм за маршрутизиране. Това е честа точка на провал: описанието не е вътрешна документация за това какво прави умението. То представлява инструкции за модела за това кога да зареди умението. Следователно често ще виждате „Load when“ („Зареждане при“), а не „This Skill does“ („Това умение прави“). Това е важно поради начина, по който повечето реализации вмъкват описанието в контекста на модела.

Във входните данни има и „depends:“, което ви позволява да създавате йерархични зависимости между уменията, и „metadata:“, което се използва за прегледи и оценки. Различните агентни системи могат дори да дефинират свои собствени полета за входни данни, които да се използват по начин, специфичен за тези системи. Като алтернатива, специфичните за уменията метаданни могат да бъдат опаковани в помощен конфигурационен файл в JSON или YAML. Това е желателно при изграждането на агентни системи, които трябва да улесняват различни видове поведение по време на изпълнение за всяко умение, без да замърсяват контекста на модела с дреболии. И накрая, подобно поведение може да се постигне чрез премахване на входните данни на умението при четене. Computer използва тази методология, която позволява конфигурацията да бъде запазена в базовия файл SKILL.md. Необходимо е внимателно обръщане на внимание на детайлите в логиката на парсиране и може да се пожелае да се реализира условно премахване, ако има определени полета, които е полезно да присъстват в контекста на модела.

Едно умение подлежи на извикване

Едно умение подлежи на извикване. Агентът зарежда умение по време на изпълнение. Важно е да се отбележи, че уменията не винаги са пакетирани в контекста. По подразбиране повечето агентни системи разгръщат уменията прогресивно при конкретна нужда.

Има поне три нива на разходи за контекст по начина, по който сме реализирали уменията в Computer. Ето процеса:

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

Computer копира директорията на умението в изолираната пясъчна кутия за изпълнение

Computer рекурсивно автозарежда зависимостите в тага „depends:“

След това Computer премахва входните данни и по този начин агентът вижда само тялото и допълнителните файлове

Различните агентни системи могат да изберат да показват съдържанието на уменията по различни начини. Като пример, някои системи може да изберат изобщо да не показват файловата йерархия, като оставят на модела да открие йерархията чрез операции с файловата система. Други системи могат да изберат да предоставят на модела мапинг на цялото файлово дърво до определен лимит на съкращаване и/или дълбочина. За да поддържа контекста чист, Computer пропуска пълните файлови йерархии от контекста на извикване; това обаче може да се презапише за всяко умение поотделно.

Едно умение е прогресивно

Уменията са прогресивни. В Computer съществуват три различни нива на разходи за контекст и ние понасяме и трите на различни етапи:

Трите нива на контекст за умение: индекс, пълно зареждане на умението и файлове с референции по време на изпълнение.

Computer изгражда индекс на уменията, който съдържа името и описанието за всяко налично умение. Бюджетът за това е около 100 токена на умение (по-краткото е дори по-добре). Той е толкова стегнат, защото плащате тази цена във всяка сесия, за всеки потребител. Това се вмква в системния промпт в самото начало на разговора. Моделът има достъп до куп именувани умения и описания, така че да може да реши дали да извика „load_skill()“. Прагът за попадане в този индекс е изключително висок. Вашето умение трябва да бъде много полезно, а описанието трябва да бъде изключително плътно и кратко, защото всеки плаща цената през цялото време.

След като агентната система зареди умението, се появява пълното тяло на SKILL.md. В идеалния случай основният текст не надвишава 5000 токена. Дори тогава искате всяко изречение да има значение, защото веднъж щом заредите умение, останалата част от разговора трябва да плаща за това, докато не достигнете границата на компресия. Много нишки зареждат между три и пет различни умения, което умножава тази цена. Уменията с много излишна информация почти сигурно ще влошат другите умения, както и общите възможности на агентите. Накратко, ако вашето умение се зареди и не свърши правилната работа, това е загубен контекст.

Крайното ниво на прогресия са скриптовете или специалните случаи, като подвмения или форматиране. Тук е мястото, където искате да поставите неограничена условна разклонена логика. Агентът ще я използва само когато е необходимо, което означава много по-нисък праг за това какво искате да поставите тук.

В индекса всеки токен е важен. Зареденото тяло на умението е по-свободно, а времето за изпълнение е най-свободно. Това могат да бъдат 20 000 токена или нула токени. Това е нивото, на което може да помислите за разширяване на контекста на модела по прогресивен начин.

Кога ви е нужно умение?

Екипът на Agents често е помолен да изрази мнение дали дадено умение е наистина необходимо за дадена област или случай на употреба. Много рядко имаме категоричен отговор само от първични принципи. Единственият начин наистина да разберете това е да започнете с вашия агент без умението, да стартирате няколко основни заявки и след това да прецените дали агентът се справя добре.

Кога ви е нужно умение

Има много задачи, които са в рамките на разпределението за обучени модели. Трябва да приложите умение само ако искате да промените това поведение по някакъв специфичен начин, който не можете да постигнете например с едно изречение във вашия промпт. Така че имате нужда от умение, когато агентът ще сбърка без специален контекст, или ако има някаква неконсистентност или недетерминираност, която трябва да бъде изключително постоянна при различните изпълнения.

Възможно е вашите знания да са трайни, но да не присъстват в обучителните данни. Може да има крайни срокове или специфични за предприятието работни процеси, или пък да става въпрос за въпрос на вкус. Например имаме няколко свързани с дизайна умения в 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-и за пет минути, резултатите почти сигурно ще бъдат под средното ниво. Всъщност ранните изследвания са показали, че ако използвате големи езикови модели (LLM) за писане на умения, моделът вероятно няма да се възползва от това: „Самогенерираните умения не носят никаква полза средностатистически, което показва, че моделите не могат надеждно да създават процедурните знания, от чието консумиране се възползват“.

Как да изградите умение

Казано по друг начин, трябва да вмъкнете своето мнение във всяко умение, което пишете. Следвайте тези стъпки.

Стъпка 0: Напишете оценките

Напишете някои от оценките първи. Можете да набавите случаи за оценка от:

Реални потребителски заявки: вземете извадка от продукцията или от вашия доверен кръг

Известни грешки: Агентът се е провалил, защото умението не е съществувало

Объркване със съседни: Близо до границата на вашата област, но се маршрутизира към друго умение

Най-малкото трябва да се уверите, че тествате дали умението се зарежда, когато е необходимо. В идеалния случай взимате извадка от някои от тях, може би от производствена среда. Може също така да помислите за известни случаи на грешки: възможно е цялата причина да сте решили да напишете умението да е заради конкретна грешка, която сте забелязали, или пък правите рефакторинг и има известно объркване в две близки области, покрити от едно умение.

Започнете с подобни отрицателни и положителни примери. Отрицателните примери са изключително мощни и могат да имат по-голямо значение от положителните.

Стъпка 1: Описанието

Това е най-трудният ред в умението. Това е задействащ механизъм за маршрутизиране, а не документация. За да улучите името и описанието правилно, съдържанието на умението не ви интересува. Интересува ви единствено дали умението се зарежда и вмъква в правилните точки и не съдържа странични ефекти извън целта, което е основният режим на провал. Всеки път, когато добавяте допълнително умение, рискувате да направите всяко друго умение малко по-лошо, така че трябва да се уверите, че минимизирате регресията.

Отново, лошото описание описва какво прави умението или защо то е полезно. Едно хубаво описание казва кога агентът трябва да зареди умението. Например, да речем, че имате нещо за наблюдение на заявки за сливане (pull requests). Не пишете какво прави умението. Напишете какво казват инженерите, когато са разочаровани и искат да се уверите, че техният PR работи, като „babysit“ („гледане като дете“), „watch CI“ („наблюдение на CI“) или „make sure this lands“ („уверете се, че това ще мине“).

Ето кратка контролна списъка:

Започва с „Load when...“

Цел от 50 думи или по-малко

Описва намерението на потребителя, в идеалния случай от реални заявки

Не обобщава работния процес

Реалните заявки са това, което можете да покриете в съотношение 80-20. Обикновено два или три примера работят добре. Не е лесно да добавите точно и само толкова, колкото ви е необходимо.

Стъпка 2: Напишете тялото

След това напишете съдържанието на самото умение. Обърнете внимание, че това не е Стъпка 0 или Стъпка 1.

Комуникирането на работни процеси към голям езиков модел е напълно различно от комуникирането на работни процеси към колега или дори към вашата система за изпълнение. Когато изучава нов софтуерен инструмент, инженерът може да се наложи да прочете документацията, да получи разходка от някой с опит и да се научи как да използва инструмента. Междувременно, за почти всеки софтуерен инструмент, който съществува поне от една година, просто трябва да споменете името му и моделът разполага с цялата необходима му информация.

Когато пишете тялото, пропуснете очевидните неща. Много инженери имат достатъчно опит в писането на readme.md файлове, които изброяват всяка команда, която някой трябва да изпълни. Лесно е да се върнете към това, когато пишете умение, защото се чувства сякаш пишете документация, но ако направите това, вашето умение ще бъде боклук. Така че не изписвайте поредица от команди.

Например не е нужно да пишете: „git log # намерете комита; git checkout main; git checkout -b <clean-branch>; git cherry-pick <commit>;“

Вместо това напишете: „Приложете комита (cherry-pick) върху чист клон. Разрешете конфликтите, като запазите намерението. Ако не може да премине чисто, обяснете защо.“

Моделът ще се справи много по-добре с второто, отколкото с прекалено предписващата поредица от команди на първото, особено когато нещата се объркат. Не налагайте строги ограничения и не бъдете прекалено предписващи, което е крехко, а вместо това бъдете гъвкави, където множество подходи могат да работят. Отново, добрата документация за хора най-често е лоша документация за модели.

След това се съсредоточете върху уловките или отрицателните примери. Те са съдържание с изключително висока стойност, защото често насочват модела по отношение на това какво да не прави. Ако добавяте ред всеки път, когато агентът се спъне, ще се учите, като го стартирате, и уловките ще растат органично.

И накрая, ако има някаква част, която е условна или изключително тежка като съдържание, извадете я от SKILL.md, който е центърът, и я поставете в една от спиците. Поставете я в аксесоарен файл, който може да бъде прогресивно зареден, в който ще се потопим след малко.

Стъпка 3: Използвайте йерархията

Възползвайте се от йерархията на уменията, когато имате скрипт, референтни материали или използвате някакъв специфичен инструмент:

Препоръчителни употреби за скриптове, референции, ресурси и конфигурация в рамките на едно умение.

За всичко, което е условно или се разклонява от основното умение, го изведете в отделна папка. Също така запомнете, че многостепенната йерархия може да се използва за особено сложни умения. За тях ще искате да помислите внимателно дали функционалността трябва да бъде реализирана монолитно, или като колекция от умения (вероятно с взаимовръзки за зареждане на базата на depends:).

Стъпка 4: Итерирайте

След това направете куп итерации на клон. Започнете на главния клон без умение, направете някои итерации, изградете вашия набор от основни заявки и изпълнете поредица от оценки. Всеки, който преглежда вашия код на умението, ще ви благодари за изпращането на една единствена промяна, пълна с набор за оценка. Прегледът на последователни постепенни промени (с изключение на нова уловка) е изключително труден, затова се опитайте да го минимизирате.

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

Стъпка 5: Пуснете

Пуснете го.

Как да поддържате умение

Сега, след като сте написали умение, трябва да го поддържате.

Маховикът на уловките

От този момент нататък вашият списък с уловки има тенденция да расте или да се променя много. Често виждаме инженери, които правят PR-и без оценки, например променят описанието. Ако променяте описанието, след като вашето умение е било обединено (merged), вие сте излезли от правилния път. Ако правите промени в нещото, което решава дали да маршрутизира вашето умение, трябва да напишете някои оценки, които подкрепят тези промени.

Уменията са предимно за добавяне. Секцията с уловки натрупва най-голяма стойност с течение на времето:

Агентът се проваля в нещо → Добавете уловка

Агентът зарежда умението извън целта → Стегнете описанието и добавете отрицателни оценки

Агентът не зарежда умението, когато трябва → Добавете ключови думи и положителни оценки

Системният промпт се променя → Проверете за конфликти или дублиране

Лесно е да забележите един единствен случай на грешка при вътрешно тестване или в продукция и да добавите уловка. Това е отрицателен пример, така че не променя изричните насоки, но дава на модела да разбере: „Хей, има тази известна грешка“.

Докато преминавате от съотношението 80-20 към постигане на 99,9% или 99,99% успеваемост, е лесно да увеличите този списък с уловки. Докато виждате тези отрицателни примери, трябва предимно да добавяте към секцията с уловки. Не трябва да добавяте по-дълги инструкции или да променяте описанието.

Набори за оценка

В Perplexity изпълняваме много набори за оценка, за да проверяваме различни неща. Съществуват зареждане на умения и четене на файлове с умения, което проверява прецизността, пълнотата и забранените проверки на самото зареждане на умението. Дали агентът ще маршрутизира вашето умение, когато се предполага, че трябва? Те гарантират, че новите умения не нарушават съществуващите граници.

Съществуват и оценки, които могат да проверят за правилно прогресивно зареждане. Агентът може да зареди умението, но чете ли аксесоарния файл или файлове? Например, ако имате финансово умение за финансови заявки, чете ли специалния файл FORMATTING.md?

Съществуват също оценки за умения, които тестват завършването на задачи от край до край в рамките на дадени области. Изпълняваме пълния цикъл на агента и използваме съдия с голям езиков модел, за да оценява резултатите въз основа на рубрика с добре дефинирани критерии.

И накрая, важно е да стартирате тези оценки спрямо различни модели. Computer поддържа поне три различни семейства модели за оркестрация: GPT, Claude Opus и Claude Sonnet. Искате да стартирате зареждането на вашите умения и домейн уменията спрямо тези различни оркестратори на агенти, за да се уверите, че няма да получите различно поведение. Sonnet и GPT се държат доста различно, когато става въпрос за умения.

Заключителни мисли и изводи

Колкото повече умения изграждате, толкова по-добри ще ставате в тяхното изграждане. Ако не автоматизирате или не се опитвате да направите по-възпроизводими задачите, които вършите ден за ден, използвайки умения, започнете незабавно.

Актът на изграждане на умения ви прави по-добри в изграждането на още умения, но освен това те са изключително добри в автоматизирането на бизнес процеси. Ако можете да опишете нещо, което правите всяка седмица преди вашата оперативка, в края на всеки спринт, или каквото и да е, което правите като инженер на дневна, седмична или дори тримесечна база, трябва да напишете умение, за да си откупите време.

Можете ли да автоматизирате постмортемите? Можете ли да преглеждате заявки за сливане? Всяка задача, която можете да направите, можете поне да накарате първото минаване да бъде агентно умение. Това ще ви спести значително време.

Въпреки това помнете, че едно умение не е лесно и дори не винаги е необходимо. По-малкото е повече. Няколко други извода:

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

Описанието е трудната част. „Load when...“ (всяка дума струва внимание).

Уловките са съдържание с изключително висока стойност. Започнете тънко, разраствайте се с провалите на агента.

Запомнете, че е лесно да счупите други предварително съществуващи умения чрез добавяне на ново умение, въпреки че не сте го докосвали (внимавайте за действие от разстояние).

Използвайте всички налични инструменти всеки път, когато пишете и поддържате умение. Ако искате да научите повече, уебсайтът на 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://perplexity.coolkeypoint.com/hub/blog/designing-refining-and-maintaining-agent-skills-at-perplexity}
}