Как настроить skills у AI-агента Pi?

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

Решение не в переписывании всей логики агента с нуля. В конце 2025 года Anthropic представила открытый стандарт Agent Skills, простой способ добавлять агенту новые модульные возможности через отдельные файлы с инструкциями. К середине 2026 года формат подхватили десятки платформ, включая Claude Code, OpenAI Codex, Cursor и OpenClaw. В этой статье разберем, что такое skills, как их подключить к собственному Pi-подобному агенту двумя разными способами, и на что обратить внимание, прежде чем ставить сторонний skill на боевой сервер.

Что такое skills у AI-агента и как они устроены

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

Формат Agent Skills, открытый стандарт, который разработала и опубликовала Anthropic в декабре 2025 года. Его официальная документация описывает главную идею так: вместо того чтобы собирать для каждой задачи отдельного агента с нуля, разработчик описывает процедуру один раз и переиспользует ее в разных инструментах. К марту 2026 года стандарт поддерживали уже больше 16 инструментов, а к середине года список вырос до 26 и более, среди них Claude Code, OpenAI Codex, Gemini CLI, Cursor и OpenClaw, где SKILL.md стал основным форматом плагинов.

Ключевая инженерная идея внутри skills называется progressive disclosure, постепенное раскрытие. Агент не держит в контексте сразу все установленные skills, это было бы дорого и медленно. Вместо этого работа идет в три уровня.

Сначала, при старте, агент подгружает только имя и короткое описание каждого skill. Независимый замер по официальным skills Anthropic показал, что на это уходит в среднем около 80 токенов на один skill, разброс от 55 до 235. Когда пользовательский запрос совпадает с описанием, агент читает полный текст SKILL.md, здесь разработчикам рекомендуют укладываться в 5000 токенов. И только если в процессе выполнения нужны дополнительные файлы из папки skill, скрипты или справочники, агент подгружает их отдельно. Такая ступенчатая архитектура позволяет держать под рукой десятки skills, не раздувая контекстное окно.

Skills, MCP и обычные функции: в чем разница

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

Обычная функция, или function calling, это классический вызов с жесткой схемой параметров: агент передает конкретные аргументы и получает структурированный ответ, поведение предсказуемо.

MCP, Model Context Protocol, работает иначе. Это протокол живого доступа к внешним системам, календарю, почте, базе данных. Между агентом и системой стоит отдельный сервер со своим runtime, вызовы идут по стандартному интерфейсу с проверкой схемы.

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

На практике skill и MCP редко конкурируют, чаще дополняют друг друга. Skill описывает процедуру целиком, а в нужный момент обращается через MCP за свежими данными из внешней системы. Например, skill для подготовки еженедельного отчета может знать формат и структуру документа, а сами цифры брать через MCP-сервер, подключенный к рабочему календарю или таск-трекеру.

Что должно быть готово перед настройкой skills

Прежде чем добавлять skills, у агента уже должны быть базовые вещи: работающий цикл обработки сообщений, модель, к которой идут запросы, и процесс, который не падает при перезагрузке сервера. Если агент запущен через systemd или в Docker с флагом restart always, это условие уже выполнено.

Второе требование, сам сервер должен быть доступен постоянно. Skills, особенно те, что выполняют код или обращаются к внешним сервисам, не имеют смысла на машине, которая уходит в сон или перезагружается без присмотра. Здесь подходит обычный VPS с root доступом, например, аренда VPS-сервера в Serverspace закрывает это требование без лишней настройки: сервер работает круглосуточно, а полный доступ позволяет ставить и тестировать любые skills без ограничений хостинга.

Как подключить skills, если агент работает на Claude API

Если ваш Pi-подобный агент построен поверх Claude, самый прямой путь, официальный Skills API.

Шаг 1. Включаем code execution и container

Skills в Claude API выполняются внутри контейнера code execution, поэтому первое условие: в запросе к Messages API должен быть включен инструмент code execution. Именно в этом контейнере запускается код skill, когда агент решает его применить.

Шаг 2. Берем готовый skill или загружаем свой через /v1/skills

Anthropic поставляет несколько готовых Agent Skills, которые можно подключить сразу по идентификатору: pptx для презентаций, xlsx для таблиц, docx для документов Word и pdf для PDF файлов. Для собственных задач, например, для скилла подготовки отчета в фирменном формате, можно загрузить свой SKILL.md через эндпоинты /v1/skills. Загруженные так кастомные skills становятся доступны всем участникам рабочего пространства.

В запросе skill указывается через параметр container вместе с типом и идентификатором, при желании можно закрепить конкретную версию. На один запрос к API можно подключить до 20 skills одновременно, Claude сам решает, какой из них подходит под конкретную задачу, ориентируясь на описание.

Как настроить skills, если агент не завязан на одну модель

Если агент работает через собственный цикл обработки, например, с моделью через Ollama или с возможностью переключаться между провайдерами, официальный Skills API не подойдет, но сам формат SKILL.md остается рабочим. Логику progressive disclosure несложно повторить в собственном коде.

Шаг 1. Создаем папку skills и структуру SKILL.md

Заводим на сервере директорию skills, и внутри для каждой новой возможности отдельную подпапку с файлом SKILL.md. В начале файла YAML блок с полями name и description, ниже, обычным текстом, сама инструкция: что делать и при каких условиях.

Шаг 2. Подгружаем name и description всех skills при старте агента

При запуске агент проходит по подпапкам, читает только фронтматтер каждого файла и добавляет короткое описание в системный промпт. Это дешево по токенам и позволяет держать библиотеку из десятков skills, не перегружая контекст с первого сообщения.

Шаг 3. Догружаем полный файл, когда задача совпадает с описанием

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

Пример: пишем свой первый skill

Проще всего разобраться на компактном примере: skill для структурированных заметок, который приводит любую мысль пользователя к единому формату перед сохранением в память агента.

Файл SKILL.md для такого случая мог бы выглядеть примерно так:

Когда пользователь просит записать заметку:
1. Сформулируй короткий заголовок из 3-6 слов
2. Определи категорию (работа, личное, идея, задача)
3. Сохрани в память в формате: [Категория] Заголовок: содержание
4. Подтверди пользователю, что сохранено, одной короткой фразой

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

Плюсы, ограничения и риски безопасности skills

У подхода с skills понятные преимущества. Новую возможность добавляют файлом, а не рефакторингом основного кода агента. Библиотека skills не раздувает контекст благодаря ступенчатой подгрузке. А формат переносится между платформами: skill, написанный для одного агента, скорее всего заработает и в другом.

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

Отдельно стоит риск безопасности. Skills это по сути код и инструкции от постороннего автора, которые получают доступ к вашему серверу. Исследование Snyk в начале 2026 года проверило маркетплейс ClawHub, площадку сообщества OpenClaw, и каталог skills.sh: у 36,8% skills в реестрах нашелся хотя бы один изъян безопасности, у 13,4% он оказался критическим, от утечки ключей доступа до команд на скачивание вредоносного кода. В сообществе задокументирована и кампания ClawHavoc: около 1200 вредоносных skills под видом полезных заставляли агентов ставить программы для кражи API-ключей, SSH-ключей и крипто-кошельков.

Практический вывод простой: относитесь к любому skill из открытого источника как к непроверенному коду. Читайте содержимое SKILL.md и вложенных скриптов перед установкой, и не ставьте новый skill сразу на боевой сервер с реальными ключами доступа. Для этого удобно держать отдельный тестовый VPS: например, развернуть VPS в Serverspace можно за несколько минут, прогнать skill там и только потом переносить его в рабочее окружение агента.

Практические сценарии: для чего добавлять skills личному агенту

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

Заметки и база знаний со структурой. Вместо бессвязного текстового файла агент приводит каждую мысль к единому формату и потом может быстро найти нужную запись.

Создание документов по запросу. По аналогии с готовыми skills docx и pdf от Anthropic, свой skill собирает письмо, отчет или счет в фирменном формате прямо по сообщению в мессенджере.

Календарь и напоминания. Skill описывает саму процедуру, а за актуальными данными обращается через MCP к внешнему календарю, хороший пример связки двух механизмов.

Анализ данных и разовые расчеты. Через code execution skill может обработать файл, который прислали в чат, и построить простую сводку.

Кастомный skill под личную рутину. Например, шаблон еженедельного отчета или чек-лист, который агент проходит по шагам каждый раз, когда звучит одна и та же фраза.

Где должны храниться данные пользователей из Казахстана

Долгосрочная память агента, о которой шла речь в самом начале, по сути и есть персональные данные пользователя: имя, предпочтения, детали проектов, история обращений. Для тех, кто настраивает Pi-подобного агента с прицелом на пользователей из Казахстана, это не теоретический вопрос.

Закон Республики Казахстан № 94-V «О персональных данных и их защите» требует, чтобы базы с персональными данными граждан РК физически находились на территории Казахстана. Речь именно про физическое размещение сервера, а не про юрисдикцию компании, которая владеет сервисом. Если агент хранит долгосрочную память о пользователях из Казахстана, этот вопрос стоит решить на старте, а не когда проект уже вырос за пределы личного эксперимента.

Отдельно стоит сказать про оплату моделей: в отличие от ряда соседних стран, из Казахстана карта местного банка обычно проходит напрямую при оплате подписок и API у Anthropic и OpenAI, без посредников и обходных схем.

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

Skills, MCP и обычные функции: сравнение в таблице

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

Частые ошибки при настройке skills

Слишком длинный SKILL.md. Если пытаться описать все нюансы и исключения в одном файле, инструкция начинает противоречить сама себе, а агент путается, вместо того чтобы четко следовать шагам. Лучше держать основной файл компактным и выносить детали в отдельные справочные файлы.

Расплывчатое описание. Самая частая причина, по которой skill вообще не срабатывает, не ошибка в инструкции, а нечеткое поле description. Агент просто не понимает, в какой момент этот skill стоит применить.

Установка из непроверенных источников без ревью. Ставить skill из открытого маркетплейса не глядя, все равно что запускать неизвестный скрипт с правами root.

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

Пропуск теста в изолированной среде. Даже skill из доверенного источника стоит сначала прогнать на тестовом сервере и посмотреть, как он себя ведет, и только потом переносить в рабочее окружение с реальными данными и ключами доступа.

Итог: что выбрать и с чего начать

Если Pi-подобный агент построен на Claude API, проще всего идти через официальный Skills API: включить code execution, подключить готовый skill по идентификатору или загрузить свой через /v1/skills. Если агент работает с разными моделями или собран на собственной логике, формат SKILL.md остается рабочим, разницу составляет только то, что подгрузку и активацию skills нужно реализовать в коде агента самостоятельно.

В обоих случаях имеет смысл начинать с одного-двух skills, протестированных на отдельном сервере, и расширять библиотеку постепенно, по мере того как становится ясно, какие задачи агент выполняет чаще всего вручную. Формат SKILL.md один и тот же независимо от платформы, поэтому написанный один раз skill переносится между проектами и агентами без переделки.