Как Agent Skills расходуют контекст и токены

Сколько токенов расходует Agent Skill на самом деле?

Расход контекста и токенов Agent Skills нельзя свести к одному числу. Он зависит от метаданных всех доступных навыков, активации конкретного SKILL.md, прочитанных дополнительных файлов, вызовов инструментов, длины агентского цикла, модели и кэша. Корректная оценка - разница между одинаковыми успешными задачами с навыком и без него.

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

Agent Skill хранит повторяемый способ работы в инструкции и связанных материалах. Если термин пока незнаком, сначала прочитайте, что такое Agent Skills. Для расчёта токенов важно другое: папка навыка не попадает в контекст целиком в момент установки.

В статье usage означает отчёт о расходе, tool calls - вызовы инструментов, input и output - вход и выход модели, cache write/read - запись и чтение кэша, retries - повторы, а compaction - сжатие истории.

Открытая спецификация Agent Skills описывает поэтапную загрузку. Сначала агент получает короткие метаданные. После выбора навыка он читает основной файл. Справочники и другие ресурсы открываются по необходимости.

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

Из каких слоёв складывается расход?

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

Эта схема отделяет прямой вклад текста навыка от поведения, которое он вызывает. Без такого разделения легко приписать SKILL.md расход, который появился из-за большого лога, повторной проверки или ещё одного обращения к модели.

Что занимают метаданные до активации навыка?

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

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

В описании agent loop Codex OpenAI указывает, что начальный input содержит преамбулу о навыках, метаданные каждого настроенного навыка и правила их использования. Anthropic также пишет, что metadata находится в system prompt до срабатывания навыка.

Ориентир около 100 токенов из спецификации полезен для проектирования, но не для счёта в платёжном отчёте. Description может быть написан по-русски или по-английски, а разные модели разбивают один текст на токены по-разному. Клиент также может добавить служебные поля.

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

Когда в контекст попадает полный SKILL.md?

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

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

Один размер файла не показывает стоимость задачи. В многошаговом процессе история передаётся в следующие обращения к модели. Anthropic объясняет, что агентский цикл повторно отправляет системную инструкцию, tools и предыдущие шаги. Кэш может сделать этот повторный вход дешевле, но текст всё ещё занимает место в context window.

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

Когда дополнительные файлы и инструменты увеличивают расход?

Дополнительный файл влияет на контекст после чтения, а инструмент - через свою схему, аргументы, результат и новые обращения к модели. Само наличие большого справочника в папке обычно не означает его полную загрузку. Зато короткая команда может вернуть длинный лог, который попадёт в следующий запрос и заметно увеличит расход.

Справочный Markdown обычно становится входом после чтения. Бинарный шаблон или asset учитывается по правилам конкретного клиента. В реализации Claude скрипт может выполняться через bash без загрузки исходного кода в контекст; модель получает его вывод. Другой клиент может сначала открыть код, поэтому это нельзя считать общим правилом.

1. 1. Описание инструмента

   Клиент передаёт модели имя, описание и схему инструмента.

2. 2. Вызов

   Модель формирует вызов и аргументы.

3. 3. Выполнение

   Клиент или сервер выполняет действие.

4. 4. Результат

   Результат возвращается модели как новый вход.

5. 5. Следующий шаг

   Агент решает, нужен ли ещё один вызов, проверка или исправление.

Документация Anthropic по tool use прямо показывает возврат tool_result в следующем запросе. OpenAI также помещает доступные tools в prompt Codex. Из-за этого список инструментов и подробные результаты нужно учитывать отдельно от текста навыка.

Preprint SkillBloat показывает предельный сценарий: специально изменённая инструкция может навязать лишние проверки, повторы и большой вывод. Это доказательство существования риска, а не типичный множитель добросовестного навыка.

Какие три метрики нельзя смешивать?

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

Максимальный контекст шага нужен, чтобы понять риск переполнения окна и вытеснения полезной истории. Это наибольшее число входных токенов в одном model call, приведённое к правилам usage выбранного провайдера.

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

Денежная стоимость применяет разные ставки. Cache read обычно дешевле обычного input, но не всегда бесплатен. Server-side web search или другая функция может иметь отдельный сбор. Умножение total_tokens на одну ставку часто даёт неверный результат.

Как рассчитать стоимость в Claude и OpenAI?

Берите raw usage каждого обращения и применяйте текущие ставки своей модели и продукта. В Anthropic полный вход складывается из обычных input tokens, cache creation и cache read. В OpenAI смотрите доступные для выбранной модели детали input usage, включая cached tokens и, где поддерживается, cache-write. Не переносите API-цены на подписку Codex или ChatGPT без проверки тарифа.

Для Anthropic API полный вход одного запроса считается как input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Каждая категория оплачивается по своей ставке.

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

Responses API OpenAI возвращает поля входа input_tokens и input_tokens_details, выхода output_tokens, детализацию рассуждения и общий итог. Для предварительного расчёта существует POST /responses/input_tokens. Поле cached_tokens входит в детализацию input, поэтому его нельзя автоматически прибавлять к общему входу второй раз.

Сохраните модель, тариф и дату рядом с расчётом. Смена модели, региона обработки, speed mode или правил кэша требует нового пересчёта.

Как провести собственный A/B/C/D-тест?

Проведите четыре условия в чистых сессиях: без навыка; с установленным, но нерелевантным навыком; с активированным SKILL.md без дополнительных материалов; с нужным reference или инструментом. Между сопоставимыми ветками сохраняйте модель, prompt, файлы, tools и критерии результата. Запишите usage каждого шага и повторите условия минимум три раза.

1. 1. Зафиксируйте окружение

   Запишите клиент и версию, точную модель, effort, лимиты, список tools, версию навыка, входные файлы, настройки кэша и критерии успешного результата. Для первых запусков навыка пригодится инструкция по установке в Codex и Claude Code.

2. 2. Условие A - навык отсутствует

   Запустите основную реалистичную задачу без проверяемого навыка. Сохраните raw usage, tool calls, итог и результат проверки.

3. 3. Условие B - навык установлен, но не должен сработать

   На одинаковом нерелевантном запросе сравните чистую сессию без навыка и с ним. Эта разница приближённо показывает метаданные и discovery-обвязку.

4. 4. Условие C - навык активирован

   Повторите основную задачу из A с теми же файлами и tools. Выберите сценарий, которому не нужен дополнительный reference. Разница A/C показывает полный end-to-end эффект навыка, а не только размер SKILL.md.

5. 5. Условие D - нужен reference или tool

   Возьмите заранее определённый сценарий, где дополнительный материал или инструмент действительно необходим. Запишите прочитанные файлы, размеры результатов и дополнительные model calls. Не называйте C/D чистым выделением одного файла, если сами задачи различались.

6. 6. Соберите usage по шагам

   Для каждого обращения сохраните input, cache write, cache read, output, reasoning tokens, вызовы tools, размер результатов, retries и compaction. Храните исходный JSON, чтобы пересчитать цену после изменения тарифа.

7. 7. Повторите и чередуйте порядок

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

8. 8. Сопоставьте расход с качеством

   Считайте цену только для результатов, прошедших одинаковые критерии. Подробный порядок парной оценки описан в статье как оценить эффективность Agent Skill.

Как интерпретировать результат без ложной экономии?

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

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

• Длинные metadata у большого числа навыков.
• Перегруженный основной файл.
• Reference, который читается целиком.
• Подробный stdout или ответ API.
• Лишние retries и проверки.
• Нестабильный prompt prefix, который мешает cache hits.

Preprint SWE-Skills-Bench использовал парные условия, закреплённые commits, контейнеры и детерминированные тесты. Авторы получили очень разный token overhead между 49 навыками, включая рост до 451% при нулевой разнице pass rate. Это результат конкретного предварительного исследования, а не прогноз для вашей задачи.

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

Где проверить механику и числа?

Для архитектуры используйте спецификацию Agent Skills и официальные документы Anthropic и OpenAI. Для usage и стоимости сверяйтесь с API reference и текущим прайсом в день расчёта. Preprint-исследования полезны как примеры методики и возможного разброса, но их проценты нельзя переносить на другой клиент, модель или задачу.

• Agent Skills specificationProgressive disclosure, поля metadata и рекомендации к структуре.
• Agent Skills у AnthropicЗагрузка metadata, SKILL.md, resources и исполнение скриптов в Claude.
• Unrolling the Codex agent loopСостав начального input, tools, prompt caching и compaction в Codex.
• Skills в Responses APIBundle, container и исследование инструкций через shell.
• Token counting AnthropicПредварительный подсчёт структурированного входа для выбранной модели.
• Messages API usage AnthropicПоля обычного входа, cache write/read и выхода.
• Responses API usage OpenAIInput details, output и reasoning breakdown.
• SkillReducerPreprint об адаптивном выборе содержимого навыка.
• SWE-Skills-BenchPreprint с парным сравнением программных навыков.
• SkillBloatPreprint о предельном сценарии раздувания агентского цикла.

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