Агентные среды разработки, такие как Claude Code, Cursor, OpenCode и другие, создают ощущение, что модель понимает систему, внутри которой работает. На практике это не так.
Я столкнулась с этим, когда пыталась настроить OpenCode под свои задачи и обнаружила, что модель не понимает собственную конфигурацию.
В этой статье я разберу:
- почему агентные IDE не используют skills автоматически
- почему они не понимают собственную архитектуру
- и как настроить skills, чтобы они действительно работали.
Модель просто не использует skills
В OpenCode, Cursor, Claude Code и других агентных средах разработки поведение модели можно настраивать через skills (скиллы), агентов и команды. Это основной механизм кастомизации — способ адаптировать модель под конкретный проект.
Когда начинаешь использовать их на практике, возникает первый разрыв с ожиданиями: модель их просто не использует.
Скилл может лежать в проекте, быть правильно оформленным и напрямую относиться к задаче. Но модель продолжает отвечать так, как будто его нет.
Если попросить её создать новый скилл — результат выглядит правдоподобно, но не работает. Она генерирует файл, похожий на правильный, но не соответствующий реальным требованиям системы. Только после прямого указания открыть документацию инструмента ситуация начинает меняться.
Модель научилась воспроизводить формат. Но не понимает, как именно работает этот механизм.
Skill — это не модуль. Это текстовая инструкция
Модель интерпретирует скилл как отдельный программный компонент: модуль, инструмент или функцию, которая должна каким-то образом подключаться и выполняться. Она пытается найти момент «запуска» и понять, по какой логике этот компонент влияет на результат.
Но в реальности никакого исполнения нет. Когда модель использует skill, его содержимое передаётся ей как обычный текст. Скилл работает не потому, что что-то запускается, а потому что модель видит дополнительный текст и учитывает его при генерации ответа.
Это ключевой разрыв: модель может создать скилл по документации, но при этом не понимать, как именно он работает. Для неё это внешний элемент системы с неочевидной логикой, а не инструкция, которая напрямую влияет на её собственное поведение.
Документация помогает создавать скиллы — объясняет формат, расположение, синтаксис. Но она не объясняет самой модели, что содержимое файла не подключается как отдельный компонент, а передаётся ей же как часть входных данных. Это не ошибка конкретной реализации, а следствие архитектуры.
Агент не может настроить себя сам
Наличие инструкций само по себе ничего не гарантирует. Пока явно не прописано, когда именно нужно использовать скилл, модель может полностью игнорировать его существование.
Это означает простую вещь: нельзя установить OpenCode или Cursor и ожидать, что модель сама корректно настроит себя под проект. Можно попросить её создать скиллы, агентов или правила — она это сделает. Но их корректность будет зависеть не от реальной архитектуры системы, а от её предположений о том, как подобные системы устроены.
Рабочая конфигурация появляется только после того, как пользователь сам описывает её в явном виде: читает документацию, формализует правила и фиксирует их в инструкциях. Если этого описания нет, модель не знает, на что опираться.
Важно, что меняется не система, а инструкция для модели. Архитектура остаётся той же — меняется только текст, на который она опирается.
Почему это не решено на уровне самих моделей
В теории это могло бы работать иначе. Если бы существовали модели, специально обученные на архитектуре конкретной агентной среды и синхронизированные с её конфигурацией, они могли бы ориентироваться в ней напрямую. Но в текущей реализации агентных систем используется универсальная модель, которая не обладает встроенным знанием о конкретном экземпляре системы, внутри которой она запущена.
Как я решила проблему
В качестве основы я использовала архитектуру из проекта Superpowers:
https://github.com/obra/superpowers
Superpowers — это open-source набор skills и правил работы для агентных сред разработки. Ключевой элемент — отдельный стартовый скилл, который загружается в начале сессии и определяет правила использования всех остальных.
Вот его ключевая часть:
Prompt--- name: using-superpowers description: Establishes how to find and use skills. Requires invoking skills before any response. --- <EXTREMELY-IMPORTANT> If there is even a 1% chance a skill might apply, you MUST invoke it. If a relevant skill exists, you DO NOT have a choice. You MUST use it. This rule applies BEFORE any response, including clarifying questions. </EXTREMELY-IMPORTANT> ## The Rule Invoke relevant skills before taking any action. Do not answer, explore, or gather information until you have checked for applicable skills. If a skill applies, follow it exactly.
Это обычный md-файл в конфигурации агентной системы. Его задача — зафиксировать обязательное правило: перед любым ответом агент должен проверить доступные инструкции и применить подходящие.
После добавления такого правила поведение меняется. Агент больше не «решает», учитывать инструкции или нет. Он обязан проверить их перед любым ответом. Это работает в Cursor, Claude Code, Kilo Code и других похожих системах — везде, где можно добавить стартовый скилл или системную инструкцию.