Perplexity опубликовали внутреннее руководство по созданию навыков для агентов

Perplexity выложили в открытый доступ своё внутреннее руководство по проектированию Agent Skills — модульных навыков, на которых работают их агенты. Документ большой, но главное в нём — не рецепты, а полный разворот привычного мышления разработчика.

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

Zen of Skills: пять принципов наизнанку

Они взяли классический Zen of Python и показали, что при создании навыков каждый принцип работает наоборот.

«Простое лучше сложного» → Навык — это папка, а не файл. Внутри: SKILL.md с инструкциями, scripts/ с кодом, references/ с тяжёлыми документами, assets/ с шаблонами, config.json с настройками. Когда Perplexity создавали навыки для налогового законодательства США (1 945 секций), плоская структура сработала хуже, чем отсутствие навыка вообще. Только трёхуровневая иерархия с навигационными гайдами дала результат.

«Явное лучше неявного» → Активация навыка — это неявное сопоставление паттернов. Агент сам решает, когда подключить навык, по короткому описанию в индексе. Информация раскрывается прогрессивно: сначала индекс, потом тело навыка, потом вспомогательные файлы — только когда они реально нужны.

«Разреженное лучше плотного» → Контекст стоит токенов. Каждое предложение в навыке оплачивается вниманием модели. Максимум сигнала на токен — вот реальный критерий качества.

«Особые случаи не настолько особые, чтобы нарушать правила» → Gotcha'и — записи о том, где агент ошибся — это и есть самый ценный контент в навыке. Они несут больше пользы, чем позитивные инструкции.

«Если реализацию легко объяснить — идея хорошая» → Если что-то легко объяснить, модель уже это знает из обучающих данных. Такую строчку нужно удалять. Навык существует только для того, что модель сама не знает.

Налог на контекст: три уровня стоимости

Каждый навык в Perplexity Computer проходит через три уровня, и каждый стоит по-разному:

Индекс (~100 токенов на навык) — название и описание попадают в системный промпт каждой сессии, для каждого пользователя. Вы платите этот налог всегда. Планка качества здесь максимальная: описание должно быть до 50 слов и начинаться с «Load when…», а не пересказывать, что навык делает.

Загрузка (~5 000 токенов) — тело SKILL.md, когда агент решил подключить навык. Каждое предложение здесь утяжеляет остаток разговора. Типичный тред загружает 3–5 навыков, и они конкурируют за внимание модели.

Рантайм (без ограничений) — скрипты, справочники, вспомогательные файлы. Загружаются только по запросу, поэтому здесь можно позволить себе объём.

Если предложение в навыке не меняет поведение агента — оно не имеет права там находиться.

Описание навыка — самая сложная строка

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

Пример из руководства: для навыка мониторинга PR не пишите «отслеживает статус pull request». Пишите слова, которые реально произносят инженеры: «babysit my PR», «watch CI», «make sure this lands». Описание строится от реальных запросов пользователей, а не от внутренней логики.

Gotcha'и как flywheel

Самый практичный паттерн из всего руководства. Навыки растут не за счёт новых инструкций, а за счёт записей об ошибках:

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

Чем дольше навык живёт в продакшене, тем точнее он работает. При этом тело навыка почти не меняется — растёт именно секция gotcha'ев.

Отдельно Perplexity подчёркивают: исследования показали, что LLM не могут сами писать навыки, от которых потом получают пользу. Самогенерация не работает. Навык — это инжиниринг с мнением, опытом и итерациями, а не одноразовый промпт.

Perplexity фактически описали новую дисциплину — Skill Engineering. Кто строит агентов — читать обязательно.

Полный текст руководства

По теме

• Статья: Мета-навык против навыка: почему чужой промпт не изменит вашу работу с ИИ
• Блог: Два правила для SOUL.md, которые делают ИИ-агента по-настоящему полезным
• База знаний: MCP (Model Context Protocol) — стандарт подключения ИИ к внешним системам

Если вы уже строите агентов или только проектируете архитектуру навыков для своей системы — разобраться в этом проще вместе.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov