Агент говорит «не умею», хотя скилл у него есть: как найти причину и починить

Коротко

• Откройте /context list: если в строке Skills list символов почти столько, сколько разрешает maxSkillsPromptChars, каталог скиллов не помещается в промпт целиком.
• Пишите description теми словами, которыми ставите задачу. Поиск лексический, имя и описание весят в нём вдвое больше тела скилла.
• Если поиска нет, назовите скилл сами: /skill <имя> задача работает всегда.

Проверено по документации OpenClaw 2026.10.3, октябрь 2026; запуском конфиги не проверялись.

Откуда берётся «не умею»

В выпуске №13 подкаста ClawCast ведущий рассказал, что когда-то у него было около десяти скиллов. Теперь к своим и найденным добавились те, что агент написал себе сам, и всех их уже нет смысла держать в контексте. Отсюда раздражающая сцена: агент отвечает, что не знает, как это сделать. Ему напоминают про скилл, и он соглашается.

Механика простая. В системный промпт OpenClaw кладёт не сами скиллы, а их каталог: имя, описание и путь к SKILL.md. Полный текст агент читает, когда решит, что скилл подходит. Каждая запись стоит около 97 символов плюс длина имени, описания и пути. Посчитаем на условных числах: имя 20 символов, описание 150, путь 50. Сто скиллов дадут 100 × (97 + 20 + 150 + 50) ≈ 31 700 символов, около 8 тысяч токенов.

Потолок задаёт skills.limits.maxSkillsPromptChars, для отдельного агента — agents.entries.<id>.skillsLimits.maxSkillsPromptChars. Значение по умолчанию docs не называют, в примерах стоят 18 000 и 6 000. При 18 000 и наших условных числах полный каталог вмещает меньше 57 скиллов: 18 000 ÷ 317, и ещё место занимает вводный блок. Посчитать свой порог можно так: бюджет ÷ (97 + имя + описание + путь). Есть и второй лимит, по числу скиллов (skills.limits.maxSkillsInPrompt), но docs его только упоминают.

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

Агент выбирает скилл по описанию. Если описание обрезано или скилла нет в списке, выбирать не из чего. Так и получается «не умею».

Всё это про встроенный рантайм OpenClaw. У Codex-харнесса и CLI-бэкендов свои правила промпта.

Как понять, что вы упёрлись в бюджет

1. /context list в чате. В ответе есть строка вида Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills). Она считает только то, что попало в промпт. Если символов почти столько же, сколько в вашем maxSkillsPromptChars, вы у потолка (это наш вывод, docs так прямо не пишут).
2. /context detail показывает записи скиллов по размеру (Top skills (prompt entry size)). Так видно, чьи описания длиннее всех.
3. openclaw skills check --agent <id> перечисляет, какие скиллы готовы к работе и видны агенту. Его число может быть больше, чем в /context, но разница не обязательно сидит в бюджете. check учитывает и скиллы с disable-model-invocation: true. Их видно в списке команд, но в промпт они не попадают, и поиск их не покажет. Зато check выводит отдельным списком скиллы с невыполненными требованиями (Missing requirements): их нет ни в промпте, ни в поиске.

Когда каталог пришлось сжать или обрезать, OpenClaw добавляет в промпт пометку со ссылкой на openclaw skills check. Её видит агент, а вы — только если посмотрите промпт целиком.

Что делает поиск

Маленький каталог виден целиком, как и раньше. Для того, что не влезло, у агента есть два инструмента, если их пропускает политика инструментов:

• skills_search({ query, limit? }) ищет по именам, описаниям и началу текста инструкций. По умолчанию возвращает 5 результатов, максимум 20. В ответе имена, пути и укороченные описания. Флаг hasMore говорит, что совпадений больше.
• skills_read({ name }) загружает весь SKILL.md по точному имени. Если имя известно, искать не нужно.

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

Чего поиск не делает:

• не ходит в ClawHub и ничего не ставит;
• не даёт права выполнять команды из найденного скилла;
• не показывает выключенные, отфильтрованные, скрытые от модели скиллы и скиллы с невыполненными требованиями.

Имена и описания ищутся по всему каталогу, а текст скиллов — частично: первые 1024 скилла по алфавиту, не больше 16 КиБ с каждого и 4 МиБ на всех.

Как писать name и description, чтобы скилл находился

Поиск сравнивает слова, а не смысл. Имя и описание весят вдвое больше тела, точное совпадение имени всегда выходит первым. Как индекс режет имена с дефисами и справляется ли с русскими падежами, docs не говорят, поэтому правила ниже — наш вывод из этих двух фактов:

• Имя — то, как вы называете задачу. У invoice-monthly больше шансов найтись по слову «invoice», чем у fin-proc-v2 по чему-нибудь. По docs имя пишется строчными буквами, цифрами и дефисами и совпадает с именем папки.
• Описание — одна строка до 160 символов со словами из задачи: что на входе и что получится. «Сверяет счета поставщиков с выпиской и готовит список расхождений» лучше, чем «Финансовый помощник».
• Язык описания — язык ваших задач. Если вы пишете агенту «сверь счета», а описание на английском, слова не совпадут. Можно дать оба: «счета (invoices)». Ключевое слово пишите в той форме, в какой его обычно произносите.
• Главное слово — в начале описания. С какой стороны укорачивают описания, docs не говорят. Короткое описание с главным в начале переживёт сокращение в любом случае.

Короткие описания заодно экономят место, и в каталог влезает больше скиллов. Как решать, что вообще стоит делать скиллом, мы разбирали в статье «Сделал дважды — сделайте скилл».

Когда поиска нет

• Политика инструментов. Без разрешённого skills_search поиска нет.
• Нет права читать. Тогда поиск идёт только по именам и описаниям. Разрешение на read даёт и skills_read, но явный запрет skills_read сильнее. Разрешение на поиск чтения не даёт.
• Песочница. Ищутся только скиллы, которые туда доставлены и читаются. Лимит передачи в 8 МиБ поиск не расширяет.
• Отдельные удалённые воркеры, которые выполняют прогон вне Gateway. Поиска у них нет, полный каталог ищется только в прогоне на самом Gateway.
• Частичное покрытие. В ответе поиска есть поле coverage (bodyIndexed, metadataOnly, truncatedBodies). Если тела прочитаны не все, пустой результат не доказывает, что скилла нет.

Что делать тогда:

1. Назвать скилл самому. /skill <имя> задача по docs работает всегда. В Control UI можно набрать $ и выбрать скилл из списка; имена команд приводятся к a-z0-9_, так что дефис, судя по docs, станет подчёркиванием, и имя надёжнее брать из списка. Скиллы с disable-model-invocation: true в этом списке нет, но /skill их вызывает, а скилл с user-invocable: false так не вызвать. Файл скилла агент всё равно читает сам, так что право на чтение нужно.
2. Сузить каталог через список разрешённых скиллов агента agents.entries.<id>.skills. Непустой список заменяет общий целиком.
3. Поднять бюджет именно этому агенту через skillsLimits.maxSkillsPromptChars, если окно модели позволяет.
4. Выключить скиллы, которые больше не нужны.

После правки начните новую сессию (/new) и снова откройте /context list: в Skills list скиллов должно стать больше или символов меньше, смотря что меняли. Откат — вернуть прежнее значение.

Где ломается

• Свежий скилл не виден. Список скиллов и индекс поиска фиксируются на старте сессии. Изменённый SKILL.md подхватывается на следующем ходе, если работает слежение за папками. Если оно выключено или сессия старая, начните новую (/new) или перезапустите Gateway. Это касается и скиллов, которые агент написал себе сам.
• Ноль скиллов в /context. Если во встроенном рантайме запрещены и read, и skills_read, каталог убирается из промпта совсем (кроме Code Mode, где модель вызывает инструменты из программы). Помогает только вернуть одно из этих прав.
• Плохое описание. Описание «помощник для разного» поиск не спасёт: по нему не найти ни одну задачу.

Если строка Skills list далеко от вашего бюджета, делать ничего не нужно: каталог виден целиком.