Новейший тренд 2025–2026: вместо жёстких графов (LangGraph) — композируемые capabilities и skill-пакеты (SKILL.md), которые агент подгружает сам по описанию. Разбираем на Pydantic AI и Anthropic Agent Skills.
Классический агент: все тулы и инструкции в одном конструкторе, контекст раздувается сотнями определений, поведение зашито в код (граф) или в один гигантский промпт.
Два симптома:
Ответ индустрии — прогрессивное раскрытие: показывай агенту только описания, грузи детали когда понадобились. Отсюда два паттерна.
Capability — переиспользуемая, композируемая единица поведения агента. Вместо того чтобы пихать всё в конструктор (instructions здесь, tools там, model settings отдельно), ты упаковываешь связанное поведение в одну capability и передаёшь через параметр `capabilities`.[111]
Capability может давать любую комбинацию:[111]
Ключевое: «Whether you're building a memory system, a guardrail, a cost tracker, or an approval workflow, a capability is the right abstraction».[111]
Capabilities бывают always-on или loaded on demand — модель сама решает, когда подгрузить (например, capability «refunds» загружается только когда разговор про возвраты).[111]
Пример из доков — банковский support-агент: capability `customer-context` (имя + баланс из БД) всегда, capability `refunds` (статус возврата) — on-demand, defer_loading=True.[78]
Готовые capability-наборы: Memory, Subagents, Guardrails, Spend Limits, Tool Search, Compaction, Web Search, MCP, FileSystem, Shell — из pydantic-ai core и pydantic-ai-harness.[111][116]
Отдельная capability в core: вместо того чтобы тащить сотни определений тулов в каждый промпт — загружай определения по требованию.[111] Это прямой ответ на проблему «агент теряется в куче тулов» из урока 0004.
Agent Skills — организованные папки инструкций, скриптов и ресурсов, которые агент обнаруживает и загружает динамически. Anthropic запустила в октябре 2025, в декабре 2025 — как открытый стандарт (agentskills.io), через 4 месяца репозиторий набрал 62k+ GitHub-звёзд, скиллы делают Atlassian, Figma, Canva, Stripe, Notion.[112][115]
Формат: директория с `SKILL.md` (YAML frontmatter: name, description) + опционально scripts/, references/, assets/.[113][114]
Метафора Anthropic: «собрать скилл — как написать онбординг-гайд для новичка».[112]
| Уровень | Когда грузится | Стоимость | Что |
|---|---|---|---|
| L1: metadata | Всегда (при старте) | ~100 токенов на скилл | name + description из frontmatter |
| L2: instructions | Когда скилл триггернулся | < 5k токенов | Тело SKILL.md |
| L3: resources/scripts | По мере надобности | 0 пока не accessed | Справочники; скрипты выполняются, в контекст идёт только вывод[113] |
Скрипты — важная деталь: код скрипта НИКОГДА не входит в контекст, только его вывод. Это детерминированность без налога на токены.[113]
Skill — это не исполняемый код и не обычный тул. Это meta-tool с именем `Skill`, который при вызове расширяется в промпт-инструкции и модифицирует контекст.[114]
Разница с тулами:[114]
| Аспект | Традиционные тулы | Skills |
|---|---|---|
| Execution model | Синхронный вызов, возвращает результат | Prompt expansion: подготавливает агента |
| Возврат | Немедленный результат | Изменение контекста разговора |
| Пример | Read, Write, Bash | pdf, skill-creator |
| Concurrency | Обычно безопасно | Не concurrency-safe |
Выбор скилла — чистое LLM-рассуждение: нет алгоритмического роутинга, эмбеддингов или классификатора. Модель читает список «name: description» в системном промпте и сама решает, какой подходит.[114]
Отсюда правило: description — главный сигнал для выбора. Она должна говорить и ЧТО делает скилл, и КОГДА его использовать («Use when working with PDF files or when the user mentions PDFs, forms, or document extraction»).[113]
Скиллы не «скрыты» — модель знает о всех с первой секунды. Разница в том, что она видит только описания (L1), а полное содержимое — только выбранного.[113][114]
"pdf": Extract text from PDF documents - When user wants to extract or process text from PDF files. Это ~100 токенов на скилл.Skill с command: "pdf".pdf/SKILL.md с диска (bash) и инжектит его содержимое в контекст разговора — только теперь модель видит полные инструкции.Аналогия: новичку в банке дают табличку отделов («Отдел карт — блокировки, лимиты»). Он знает, что отделы существуют. Пришёл клиент с вопросом про блокировку — он идёт в отдел карт и читает их внутреннюю инструкцию. Табличка = L1, инструкция = L2, справочники = L3.
То же для тулов (function calling): каждому тулу передаётся JSON-schema (name, description, parameters) в запросе API. Модель видит все схемы и сама выбирает, какой тул вызвать и с какими аргументами. Код тула выполняется снаружи, возвращается только результат.
Следствие: качество description = качество выбора. Смутное описание → модель не вызовет скилл или вызовет не тот. Поэтому description пишется как «что делает + когда использовать», и это тестируется на golden set, как промпт.
Частый вопрос: «У тула JSON-схема всё равно в контексте, код и раньше выполнялся снаружи — где экономия?»
Тул сам по себе контекст НЕ экономит. Схемы всех тулов (name, description, parameters) всегда в каждом запросе — это осознанный трейд-офф: компактная структура (~300 токенов на тул) за то, что модель точно знает сигнатуру и может вызвать любой. Код тула был снаружи и до скиллов.
Реальная экономия тулов — отдельная фича Tool Search / on-demand tools: в контексте только каталог имён и коротких описаний (~50 токенов на тул), полная JSON-схема подгружается для выбранного тула. Это та же progressive disclosure, применённая к тулам.
Скилл экономит инструкции — то, что иначе жило бы в системном промпте как текст. Сравни: 50 инструкций по 1000 токенов в промпте = 50k токенов в КАЖДОМ запросе. Со скиллами: 50 × ~100 токенов описаний = 5k всегда + полный текст только выбранного. Политика банка на 50 страниц не грузится, пока клиент не спросил про неё.
| Тул | Скилл | |
|---|---|---|
| Что это | Операция: выполнить и вернуть результат | Знание: подготовить агента (инструкции) |
| В контексте | JSON-схема (всегда) | Описания (всегда) + тело (по требованию) |
| Что экономит | Ничего из контекста — кроме Tool Search | Инструкции и справочники, иначе жившие в промпте |
Скилл может содержать и то и другое: SKILL.md учит «как работать с PDF», а fill_form.py внутри — детерминированный скрипт, то есть «тул» внутри скилла. Поэтому они не конкуренты: тул выполняет, скилл учит.
Паттерн: тяжёлый тул прячется за скиллом — его JSON-схема попадает в контекст только после того, как модель загрузила скилл.
"refunds": Refund eligibility and refund status.Это реализовано в Pydantic AI как capability с defer_loading=True (банковский пример с refunds[111]) и в Anthropic Skills через скрипты в скилле (код не в контексте, только вывод[113]).
Токен-математика: схема тула ~300 токенов. В базе — платишь в каждом запросе, даже когда тул не нужен. За скиллом — 0 токенов, пока не понадобился; +~100 токенов описания скилла всегда.
Подводные камни:
Это развитие правила из урока 0004 («3–5 горячих тулов в контексте, остальные за router»): теперь за router'ом скилл, а не код.
| Критерий | LangGraph (граф) | Capabilities / Skills |
|---|---|---|
| Control flow | В коде: nodes + edges, явные ветки | В модели: агент сам решает по описаниям |
| Новый сценарий | Правка графа, ретест | Новый SKILL.md/capability, без правки кода |
| Предсказуемость | Высокая — путь фиксирован | Ниже — модель может выбрать иначе |
| Контекст | Все тулы в промпте | Только описания, детали по требованию |
| Отладка | Граф виден, можно шагать | Трейс решений модели |
| Когда | Ветки известны, нужна строгость (банк, деньги) | Много сценариев, быстрое расширение |
Фраза для собеседования: «Граф — когда путь предсказуем и важна строгость: router → RAG → тул → человек. Skills/capabilities — когда сценариев много и они растут: новый скилл — это новый SKILL.md, а не правка графа. Это не либо-либо: в каре я бы держал жёсткий граф для action-путей с деньгами, а FAQ-знания и процедурные инструкции вынес бы в скиллы, чтобы контекст не раздувался».
Прогрессивное раскрытие — это?
Выбор скилла делает?
Код скрипта скилла?