claude-api и ловушка Skills: как полезный навык Claude может съесть контекст

Что произошло: один вызов, 624 401 символ и ошибка длины prompt

27 июля 2026 года в публичном репозитории anthropics/skills появился issue #1487. Пользователь DaKev утверждает, что bundled skill claude-api в Claude Code 2.1.220 на Windows 11 при вызове Skill(claude-api) вставил в сессию 624 401 символ. Автор оценил объем примерно в 156 тыс. токенов. После этого следующий ход ассистента, по его словам, завершился ошибкой Prompt is too long.

Это не официальное признание бага Anthropic, а пользовательский отчет. Но он достаточно конкретен, чтобы обсуждать не ощущение деградации модели, а инженерный риск в работе Skills. Данные о версии Claude Code, Windows 11, Git Bash и Node v24.14.0 следует читать как сведения, предоставленные автором отчета, а не как независимую верификацию.

В тот же день в репозитории появился issue #1486 со сходной претензией: claude-api раздувает контекст до состояния, когда работа становится непригодной. Там фигурируют пользовательские оценки 320 тыс. токенов и 3,50 доллара API-расходов. Второй сигнал слабее: в карточке нет столь же подробного воспроизводимого разбора. Поэтому численную основу для анализа дает #1487, а #1486 лишь усиливает подозрение.

Ключевая деталь #1487 связана не только с размером. По версии автора, в сессию попал не один компактный entry point, а 32 документа: SKILL.md и 31 reference document. Автор разбил payload на крупные зоны: shared/model-migration.md занял 143 685 символов, набор Managed Agents 202 069 символов, SKILL.md 68 375 символов, остальное 210 272 символа. Эти доли складываются в заявленные 624 401 символ.

Предмет разговора важно не подменять. Отчет не доказывает сбой Messages API и не означает, что любая модель Claude теряет контекст от любого skill. Речь о конкретной поверхности продукта: Claude Code, bundled skill claude-api, упаковке Skills и способе попадания инструкций в conversation context. Проблема может находиться не в Opus, Sonnet или Haiku, а в инженерии контекста вокруг модели.

Это не медленная деградация.

Источник: DaKev - автор issue #1487 на GitHub

Редакторский вывод: автор отчета связывает сбой с одним крупным вызовом skill, а не с постепенным накоплением истории диалога.

Цитата в переводе

«Это не медленная деградация.»

Как Skills должны работать по замыслу Anthropic

Skills в экосистеме Claude описаны как папки с инструкциями, ресурсами и иногда исполняемыми скриптами. В пользовательской документации Anthropic называет их динамически загружаемыми пакетами знаний: Claude не должен держать все содержимое в контексте постоянно, а должен выбирать релевантный skill под задачу. Для пользователя это похоже на технический справочник на полке: модель знает, что он существует, но открывает его только при необходимости.

В документации Claude Platform для Agent Skills этот принцип описан через progressive disclosure, или постепенное раскрытие информации по мере необходимости. Первый уровень включает metadata: имя и описание skill, по которым Claude решает, подходит ли он к задаче. Второй уровень включается при совпадении задачи: Claude получает полные инструкции релевантного skill.

У этого архитектурного принципа есть прямой практический смысл. Он позволяет добавлять возможности без постоянного утяжеления system prompt и без превращения каждого запроса в загрузку всей библиотеки. Claude Code добавляет собственную механику: при вызове skill отрендеренный SKILL.md входит в conversation как одно сообщение.

Документация о работе Claude Code описывает контекстное окно как совокупность нескольких источников: системных инструкций, CLAUDE.md, результатов инструментов, загруженных skills и истории разговора. Даже полезный skill после вызова становится частью конечного бюджета контекста.

Отсюда возникает риск. Progressive disclosure снижает его только при трех условиях: entry point короткий, триггеры достаточно точные, а тяжелые reference-файлы читаются по явной необходимости. Если один вызов фактически приносит крупный справочник целиком, Claude Code получает не способность по запросу, а скрытый контекстный груз.

По мере необходимости.

Источник: Anthropic Help Center - документация Anthropic о Skills

Редакторский вывод: динамическая загрузка полезна лишь тогда, когда система действительно откладывает тяжелые материалы до релевантной задачи.

Цитата в переводе

«По мере необходимости.»

Где ломается ожидание: широкий trigger и eager loading

По версии issue #1487, claude-api сработал на задаче, которая не выглядела как глубокая миграция SDK или проектирование агента. Пользователь описывает редактирование Markdown-файла с упоминаниями Claude, Opus, Fable и CLAUDE.md. Этого, по его утверждению, оказалось достаточно для вызова Skill(claude-api).

Если отчет точен, проблема начинается еще до размера файлов. Система классификации могла решить, что общий маркер бренда или модели является достаточным поводом для включения большого API-справочника. Второй слой проблемы, описанный автором, это eager loading supporting files: предварительная загрузка вспомогательных файлов без отдельного запроса.

Автор #1487 утверждает, что claude-api загрузил не только основной SKILL.md, но и набор reference-документов, включая материалы по migration и Managed Agents. Для переноса кода на новый SDK такой контекст может быть оправдан. Для правки таблицы в Markdown он выглядит избыточным. Здесь проявляется конфликт между универсальностью skill и точностью его активации.

Есть сильный контраргумент: claude-api не является маленькой подсказкой. Он должен помогать с API- и SDK-сценариями, где опасно догадываться о форме вызовов и параметрах. Большой reference способен уменьшать риск ошибок. Но он должен появляться, когда задача действительно требует API-справки, а не при каждом упоминании семейства моделей.

Для Anthropic это чувствительно, потому что Skills являются частью developer experience, а не только документационным форматом. Это способ переносить знания между Claude app, Claude Code и API-сценариями, а также строить агентные workflow. Если skill воспринимается как непрозрачный источник риска, пользователи могут отключать его превентивно.

Почему 156 тыс. токенов нельзя читать слишком грубо

Число 156 тыс. токенов звучит драматично, но его нужно оговаривать. В issue указаны 624 401 символ и приблизительная оценка около 156 тыс. токенов. Автор не раскрывает, использовал ли он официальный Token Counting API, локальный tokenizer или грубую эвристику. Корректная формулировка такова: автор issue оценил payload примерно в 156 тыс. токенов.

Фраза об исчерпанном контекстном окне тоже требует аккуратности. В описанном случае следующий API call, по словам пользователя, завершился Prompt is too long. Это не доказывает, что 156 тыс. токенов всегда достаточно для исчерпания любого доступного context window Claude.

На результат влияют модель, product-level лимиты Claude Code, уже накопленная история, CLAUDE.md, результаты инструментов, загруженные skills, auto-compaction и внутренние правила конкретной сессии. В инженерном смысле #1487 показывает не универсальный предел Claude, а опасный сценарий: один скрытый блок способен резко изменить состояние контекста.

Стоимость также нельзя считать напрямую по одному числу. В issue #1486 пользователь говорит о 3,50 доллара API-расходов, но это пользовательская оценка, а не invoice и не расчет Anthropic. На итог влияют модель, кэширование prompt, поверхность использования, подписка Claude Code или прямой API-биллинг.

Умеренная интерпретация такова: #1487 не доказывает провал всей концепции Skills. Он показывает дефектный край. При неправильной упаковке и широком trigger skill может нарушить собственную философию progressive disclosure и перенести сложность из явного кода в скрытую сборку prompt.

Что это говорит о Claude Code как среде разработки

Claude Code отличается от обычного чата тем, что модель постоянно взаимодействует с проектом: читает файлы, запускает команды, использует tools, учитывает CLAUDE.md и инструкции репозитория. Контекст здесь похож на рабочую память IDE, но имеет жесткий лимит и стоимость каждого лишнего фрагмента.

Когда skill добавляется в conversation одним сообщением и остается в сессии, это уже не просто справка. Это часть состояния инструмента разработки. В классической IDE большой reference-файл лежит на диске и почти ничего не стоит, пока разработчик его не открыл. В агентной IDE тот же reference может стать частью prompt и начать конкурировать с кодом, логами, результатами тестов и задачей пользователя.

Поэтому Claude Code нуждается в контекстной гигиене сильнее, чем чат-приложение. Агент, который умеет многое, должен понимать, когда не надо тащить в контекст все свои знания. Документация Claude Code описывает механизмы контроля контекста и факт включения skill invocation в разговор, но #1487 показывает возможный разрыв между наличием контроля и реальным developer experience.

Если предупреждение приходит после того, как сессия стала непригодной, контроль превращается в диагностику постфактум. Если Anthropic подтвердит проблему, возможными направлениями исправления могли бы быть бюджет cold invocation, предупреждение перед крупной подгрузкой, ленивое чтение reference-файлов и более строгие триггеры. Это редакционная рекомендация, а не объявленный план Anthropic.

Agent SDK и API: почему проблему нельзя свести к Claude Code

Хотя свежий сигнал пришел из Claude Code, тема шире. Agent Skills в документации Platform и Agent SDK описаны как строительный блок для агентных приложений: разработчик может упаковать инструкции и ресурсы, чтобы Claude использовал их в специализированных задачах. Речь идет не только о редакторе кода, но и об API-платформе.

Если skill становится частью агентного workflow, его размер и триггеры начинают влиять на latency, стоимость, rate limits и воспроизводимость. Разработчики могут считать skills безопасной абстракцией: положить SKILL.md, добавить supporting files и получить повторяемое поведение. Но supporting files не должны превращаться в безусловный upfront payload.

В хорошей архитектуре SKILL.md служит маршрутизатором: объясняет, когда skill релевантен, какие шаги выполнить и какой файл открыть при migration, streaming, MCP или работе с tools. В плохой архитектуре SKILL.md становится дверью, за которой модель сразу получает весь архив.

В backend-agent workflow скрытая подгрузка проявится не как визуально заметный лишний текст, а как рост latency, неожиданный счет, failure на длинной задаче или снижение качества из-за вытеснения полезного контекста. Ошибка может выглядеть как неспособность модели решить задачу, хотя ее источник находится в упаковке skill и бюджете prompt.

Это характерный этап взросления agentic tooling. Знания можно переиспользовать, но их также приходится версионировать, тестировать, профилировать и лимитировать. Skill становится зависимостью в цепочке разработки, а не просто prompt-файлом.

Корпоративный слой: Skills как часть supply chain

Anthropic развивает Skills не только для индивидуальных пользователей. В корпоративной логике skill может стандартизировать работу с внутренними форматами, отчетами, проверками, кодстайлом и API-практиками. Организационные Skills и directory делают эту модель привлекательнее: знания можно раздавать командам централизованно, а не пересылать каждому длинные инструкции.

Именно поэтому история с claude-api важна для governance, то есть правил управления и контроля. Если skill способен неожиданно добавить сотни тысяч символов, его нельзя включать в организационную среду только потому, что он официальный или полезный. Нужны проверки, похожие на review библиотек: кто автор, что внутри, насколько широк trigger, какие reference-файлы могут попасть в prompt, каков worst-case payload и как skill ведет себя на нерелевантных задачах.

В #1487 речь идет о bundled skill, а не о случайном стороннем prompt. Это усиливает эффект: инструменты, связанные с официальной экосистемой, формируют ожидания рынка. Если встроенный claude-api кажется слишком агрессивным, команды могут закладывать дополнительный контроль даже для доверенных skills.

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

Что делать разработчикам уже сейчас

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

Пользователям Claude Code стоит проверять контекст после вызова тяжелых skills и смотреть, не заняли ли инструкции непропорционально много места. Если claude-api срабатывает на нерелевантных Markdown или config tasks, его invocation можно временно ограничить через доступные настройки. Это workaround, а не универсальный совет: при работе с Anthropic API такой skill способен быть полезной справкой.

Для авторов собственных Skills правило жестче. SKILL.md должен быть коротким индексом и процедурной инструкцией, а не свалкой всего знания. Большие reference docs лучше выносить в отдельные файлы и явно описывать условия чтения: migration только при migration, pricing только при расчете стоимости, MCP только при настройке MCP, streaming только при streaming.

Командам полезно добавить автоматические проверки: считать размер SKILL.md, оценивать worst-case payload, тестировать cold invocation на типовых и нерелевантных задачах, логировать invocation, хранить changelog skills и проводить review триггеров. Хороший skill отвечает не только на вопрос, умеет ли Claude сделать задачу, но и на вопрос, сколько контекста он для этого потребляет.

• Проверяйте, какой skill был вызван и сколько контекста он занял в Claude Code.
• Не используйте широкие триггеры в виде одного названия модели, если skill нужен только для API-задач.
• Держите SKILL.md компактным, а большие справочники загружайте по условию.
• Перед включением skill для команды тестируйте не только happy path, но и нерелевантные задачи.
• Разделяйте поверхности: Claude app, Claude Code, прямой Claude API и агент через SDK могут по-разному проявлять один и тот же контекстный риск.

Какие вопросы теперь стоят перед Anthropic

У Anthropic есть архитектурная идея: дать Claude доступ к специализированным наборам навыков без постоянного перегруза контекста. Но issue #1487 поднимает вопросы, на которые нужен инженерный ответ. Мог ли Skill(claude-api) в Claude Code 2.1.220 действительно загрузить SKILL.md и 31 reference document одним payload? Какой фактический context cap применялся в описанной сессии? Должны ли migration-файлы и материалы Managed Agents загружаться только после более точной классификации задачи?

Есть и продуктовые вопросы. Нужно ли Claude Code показывать warning перед вызовом skill, если тот может добавить крупный payload? Должен ли bundled skill иметь внутренний лимит upfront-токенов? Следует ли сужать триггеры claude-api до API- и SDK-сигналов, а не до любых упоминаний Claude или названий моделей? Пока это вопросы, не факты и не планы компании.

Пользователи оценивают Skills не по красоте концепции, а по поведению в обычных сценариях. Если модель редактирует Markdown и внезапно загружает API-энциклопедию, доверие к механизму падает. Если она открывает ровно тот reference, который нужен для migration, доверие растет. Разница между этими режимами и определяет зрелость developer experience.

Что это означает на практике

Issue #1487 показывает зрелую проблему новой AI-инфраструктуры. Разработчикам все чаще приходится спрашивать не только о качестве модели, но и о том, какой контекст ей дали, кто его туда положил, сколько он стоит и можно ли было загрузить меньше.

Если Anthropic подтвердит и исправит eager loading в claude-api, это будет локальный багфикс. Более широкий урок останется: Skills становятся частью программной поставки. Их нужно проектировать, профилировать и ограничивать, иначе инструмент, который должен принести Claude нужное знание в нужный момент, сам оставит для этого знания слишком мало места.

• Issue #1487 является конкретным сигналом, но не официальным признанием бага Anthropic: оценку в 156 тыс. токенов следует атрибутировать автору issue.
• Проблема относится прежде всего к Claude Code и упаковке claude-api skill, а не к доказанному сбою Claude API как такового.
• Skills требуют дисциплины progressive disclosure: короткого entry point, точных триггеров и условной загрузки больших reference-файлов.
• Context footprint skills стоит измерять так же регулярно, как latency и стоимость API-вызовов.
• Командам нужны внутренние лимиты на размер skill invocation и review триггеров до включения skill в общую среду.

Чек-лист: проверка контекстной гигиены Skills

Используйте памятку перед добавлением skill в личный или командный workflow. Полная версия подготовлена отдельным PDF-файлом для скачивания.

Перед первым запуском

Проверьте состав skill и определите, какой объем может попасть в prompt при холодном вызове.

• Зафиксируйте размер SKILL.md и всех reference-файлов.
• Определите worst-case payload для одного invocation.
• Проверьте, какие слова, файлы и задачи могут активировать skill.
• Отделите обязательные инструкции от материалов, которые нужны только в редких сценариях.

Тестирование и эксплуатация

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

• Протестируйте skill на целевых и нерелевантных запросах.
• Логируйте invocation и изменение доступного контекста.
• Проверяйте влияние на latency, ошибки длины prompt и результаты инструментов.
• Версионируйте изменения триггеров и reference-файлов.
• Проводите review skill как зависимости в developer workflow.

Источники

• GitHub issue #1487 в репозитории anthropics/skills
• GitHub issue #1486 в репозитории anthropics/skills
• Anthropic Help Center: What are Skills?
• Claude Platform: Agent Skills quickstart
• Claude Code: Slash commands
• Claude Code: How Claude Code works
• Claude Code Agent SDK: Skills
• Claude: Organization Skills and directory

Частые вопросы

Доказывает ли issue #1487, что Claude API не работает с длинным контекстом?

Нет. Это пользовательский отчет о конкретном сценарии в Claude Code и bundled skill claude-api. Он не доказывает общий сбой Claude API или всех моделей Claude.

Откуда взялась оценка в 156 тыс. токенов?

Автор issue #1487 указал payload в 624 401 символ и оценил его примерно в 156 тыс. токенов. В отчете не раскрыт способ подсчета, поэтому число нельзя выдавать за официальное измерение Anthropic.

Почему большой skill может быть проблемой в Claude Code?

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

Нужно ли отключать Skills после этого отчета?

Нет. Практичнее проверять условия активации, размер SKILL.md и reference-файлов, а также тестировать поведение skills на целевых и нерелевантных задачах.

Как безопаснее проектировать собственный skill?

Держите SKILL.md коротким маршрутизатором, выносите объемные справочники в отдельные файлы и описывайте точные условия, при которых Claude должен их читать.

Практический чек-лист

Чек-лист контекстной гигиены Skills

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

Перед первым запуском

• Зафиксируйте размер SKILL.md и всех reference-файлов.
• Определите worst-case payload для одного invocation.
• Проверьте условия активации skill.
• Разделите обязательные инструкции и редкие справочные материалы.

Тестирование и эксплуатация

• Тестируйте целевые и нерелевантные задачи.
• Логируйте invocation и изменение контекста.
• Проверяйте latency, ошибки длины prompt и результаты инструментов.
• Версионируйте триггеры и reference-файлы.
• Проводите review skill как зависимости workflow.