Проектирование, доработка и поддержание навыков агентов в Perplexity

Продукты на базе передовых агентов Perplexity основаны на ноу-хау и экспертных знаниях в предметной области, упакованных в модульные навыки агента. Мы поддерживаем тщательно отобранную библиотеку навыков в наших технических средах. Эти навыки включают в себя многие инструменты общего назначения, обеспечивающие работу Perplexity Computer; специфические для конкретных отраслей возможности в таких областях, как финансы, право и здравоохранение; а также обширный ряд модулей для удовлетворения потребностей пользователей. Некоторые навыки вызываются редко, но являются критически важными в момент их вызова. Чтобы обеспечить неизменно превосходное качество обслуживания пользователей, команда агентов Perplexity уделяет качеству навыков такое же пристальное внимание, как и качеству кода.

Интуиция и передовые методы, необходимые для разработки высококачественного навыка, существенно отличаются от тех, что требуются для создания традиционного программного обеспечения. Команда агентов рассматривает множество запросов на включение (pull requests) от выдающихся инженеров, которые разрабатывают навыки в ходе своей работы. Результатом почти всегда являются многочисленные комментарии и предложения по доработке. Это связано с тем, что многие полезные шаблоны написания кода становятся антипаттернами при создании навыка.

Например, если взять некоторые афоризмы из PEP20 — Дзен Python, становится очевидно, что написание качественного кода на Python отличается от написания качественных навыков. Из 20 строк мудрости по крайней мере половина являются совершенно неверными или активно вводят в заблуждение при написании навыков. Вот пять из них:

Пять различий между дзеном Python и рекомендациями статьи по написанию навыков.

Это руководство является документом, который инженеры 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:», используемое для обзоров и оценок. Различные агентные системы могут даже определять свои собственные поля метаданных, которые будут использоваться специфическим для этих систем образом. В качестве альтернативы метаданные, специфичные для навыка, могут быть упакованы в вспомогательный файл конфигурации 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 токенов или ноль токенов. Это уровень, на котором вы можете подумать о расширении контекста модели прогрессивным образом.

Когда вам нужен навык?

Команду агентов часто спрашивают, действительно ли нужен навык для данной предметной области или сценария использования. Очень редко у нас есть окончательный ответ, основанный только на первопринципах. Единственный способ действительно разобраться в этом — начать работу с вашим агентом без этого навыка, выполнить несколько героических запросов, а затем понять, справляется ли агент с работой хорошо.

Когда вам нужен навык

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

Может быть, ваши знания долговечны, но отсутствуют в данных для обучения. Могут быть отсечки или специфические для предприятия рабочие процессы, или это может быть вопрос вкуса. Например, у нас в 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. » — Блез Паскаль, «Письма к провинциалу», 1657 г.

Так же, как и Паскаль, вам нужно вкладывать время в каждый навык. Написать короткий навык сложно. Если ваш навык написать легко, он, вероятно, слишком длинный или не должен существовать. Хороший навык настолько короткий, насколько это возможно.

Если вы обнаружите, что пытаетесь сгенерировать навык за один подход и выставляете PR за пять минут, результаты почти наверняка будут ниже среднего. На самом деле ранние исследования показали, что если вы используете LLM для написания навыков, LLM, вероятно, не получит от этого пользы: «Самостоятельно сгенерированные навыки не приносят пользы в среднем, показывая, что модели не могут надежно создавать процедурные знания, от потребления которых они выигрывают».

Как создать навык

Проще говоря, вам нужно внедрить свое мнение в любой навык, который вы пишете. Следуйте этим шагам.

Шаг 0: Напишите оценки

Сначала напишите несколько оценок. Вы можете найти случаи для оценки из:

Реальные запросы пользователей: выборка из продакшена или вашего круга доверия

Известные сбои: агент потерпел неудачу, потому что навыка не существовало

Путаница с соседями: близко к границе вашей предметной области, но направляется к другому навыку

По крайней мере, вы должны убедиться, что тестируете загрузку навыка, когда это необходимо. В идеале вы делаете выборку некоторых из них, возможно, из производственной среды. Вы также можете рассмотреть известные случаи ошибок: возможно, вся причина, по которой вы решили написать навык, заключается в конкретном сбое, который вы заметили, или, возможно, вы проводите рефакторинг, и есть некоторая путаница в двух близких областях, охватываемых одним навыком.

Начните с похожих отрицательных и положительных примеров. Отрицательные примеры чрезвычайно мощны и могут иметь большее значение, чем положительные.

Шаг 1: Описание

Это самая сложная строка в навыке. Это триггер маршрутизации, а не документация. Чтобы правильно выбрать имя и описание, вам не нужно беспокоиться о содержании навыка. Вас волнует только то, загружается ли навык и внедряется ли он в нужные моменты и свободен ли он от побочных эффектов вне целей, что является проблемой номер один в режиме отказа. Каждый раз, когда вы добавляете дополнительный навык, вы рискуете сделать каждый другой навык немного хуже, поэтому вам нужно убедиться, что вы минимизируете регрессию.

Опять же, плохое описание описывает, что делает навык или почему он полезен. Хорошее описание говорит, когда агент должен загрузить навык. Например, скажем, у вас есть что-то для мониторинга запросов на слияние (pull requests). Не пишите, что делает навык. Пишите то, что говорят инженеры, когда они расстроены и хотят, чтобы вы убедились, что их 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: Используйте иерархию

Используйте иерархию навыков, когда у вас есть скрипт, ссылки или вы используете какой-то конкретный инструмент:

Рекомендуемые варианты использования сценариев, справочных материалов, ресурсов и конфигурации в рамках навыка.

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

Шаг 4: Итерируйте

Затем сделайте кучу итераций на ветке. Начните на основной ветке без навыка, сделайте несколько итераций, создайте свой набор героических запросов и запустите множество оценок. Любой, кто проверяет код вашего навыка, поблагодарит вас за отправку одного изменения, укомплектованного набором оценок. Проверка последовательных инкрементальных изменений (за исключением нового подвоха) очень сложна, поэтому старайтесь минимизировать ее.

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

Шаг 5: Отправляйте

Отправляйте его.

Как поддерживать навык

Теперь, когда вы написали навык, вы должны поддерживать его.

Маховик подвохов

С этого момента ваш список подвохов будет расти или сильно меняться. Мы часто видим инженеров, которые делают PR, которые не оцениваются, например, меняют описание. Если вы меняете описание после того, как ваш навык был объединен, вы сбились с пути. Если вы вносите изменения в то, что решает, направлять ли ваш навык, вам нужно написать несколько оценок, которые поддерживают изменения.

Навыки — это в основном добавление. Секция подвохов со временем накапливает наибольшую ценность:

Агент терпит неудачу в чем-то → Добавить подвох

Агент загружает навык не по назначению → Уточнить описание и добавить отрицательные оценки

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

Изменения системного промпта → Проверить на противоречия или дублирование

Легко заметить единичный случай сбоя при внутреннем тестировании или в продакшене и добавить подвох. Это отрицательный пример, поэтому он не меняет явные руководящие принципы, но сообщает модели: «Эй, есть такой известный сбой».

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

Наборы оценок (Eval Suites)

В Perplexity мы запускаем множество наборов оценок для проверки различных вещей. Есть загрузка навыка и чтение файлов навыка, которые проверяют точность, полноту и запреты самой загрузки навыка. Будет ли агент направлять ваш навык, когда это необходимо? Они гарантируют, что новые навыки не нарушают существующие границы.

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

Существуют также оценки навыков, которые проверяют выполнение задачи от начала до конца в рамках предметных областей. Мы запускаем полный цикл агента и используем судью LLM для оценки результатов на основе рубрики четко определенных критериев.

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

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

Чем больше навыков вы создаете, тем лучше у вас будет получаться их создавать. Если вы не автоматизируете или не пытаетесь сделать более воспроизводимыми задачи, которые вы делаете на повседневной основе с использованием навыков, начните немедленно.

Сам процесс создания навыков делает вас лучше в создании новых навыков, но также они чрезвычайно хороши для автоматизации бизнес-процессов. Если вы можете описать что-то, что вы делаете каждую неделю перед стендапом, в конце каждого спринта, или что угодно, что вы делаете как инженер на ежедневной, еженедельной или даже ежеквартальной основе, вы должны писать навык, чтобы сэкономить свое время.

Можете ли вы автоматизировать постмортемы? Можете ли вы проверять пулл-реквесты? Любая задача, которую вы можете сделать, может иметь хотя бы первый проход в виде навыка агента. Это сэкономит вам значительное время.

При этом помните, что навык — это не легко и даже не всегда необходимо. Меньше — это лучше. Несколько других выводов:

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

Описание — это самая сложная часть. «Загружать при...» (каждое слово стоит внимания).

Подвохи — это контент с чрезвычайно высокой ценностью. Начните с малого, растите по мере того, как агент терпит неудачу.

Помните, что легко сломать другие уже существующие навыки, добавив новый навык, даже если вы его не касались (остерегайтесь действий на расстоянии).

Используйте все доступные инструменты каждый раз, когда вы пишете и поддерживаете навык. Если вы хотите узнать больше, на веб-сайте навыков агента есть много хороших примеров, и как наш внутренний репозиторий, так и публичная экосистема содержат много примеров хорошо спроектированных навыков.

Цитирование

@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}
}