AI-агент: это способ экономить токены, встроив инструкции прямо в npm-пакет

Разработчик опубликовал открытый подход Agent Skills, при котором ИИ-агент (это программа, которая сама выполняет задачи по цепочке, без ручного контроля на каждом шаге) получает компактные инструкции к библиотеке прямо из npm-пакета, а версия инструкций всегда совпадает с версией кода.

Проблема знакома каждому, кто работает с кодовыми агентами: агент встречает незнакомую зависимость, начинает читать исходники, типы, README, тесты, тратит токены (единицы текста, которые модель обрабатывает за один проход) и контекстное окно, а результат зависит от того, какие файлы он успел просмотреть. Автор библиотеки знает ответы заранее, но до сих пор не было стандартного канала доставки этих знаний вместе с пакетом.

Что решает Agent Skills?

• Экономит контекст модели. Вместо полного разбора исходников агент читает короткий файл SKILL.md с YAML-метаданными и пошаговыми правилами. Подробные справочные материалы лежат в папке references/ и подгружаются по мере необходимости.
• Разделяет публичный контракт и внутреннюю реализацию. Навык явно указывает, что является публичным API (набор функций, доступных внешнему коду), а что деталями реализации. Агент не лезет в приватные модули и не ломает чужой код.
• Фиксирует версию инструкций вместе с версией кода. Каталог skills/ входит в npm-артефакт. Обновили зависимость, обновился и навык. Откатили, вернулись старые инструкции. Файл package-lock.json держит всё в синхронности.
• Ограничивает опасные действия. В инструкции прописано, что агент не имеет права делать без разрешения владельца проекта: например, не должен сам решать переименовать поля базы данных при пересборке или завершать чужую транзакцию.
• Отличается от README. README объясняет пакет человеку. Навык задаёт агенту порядок работы: какие контракты изучить, что проверить, какие решения оставить за разработчиком.

Как попробовать?

1. Создайте каталог навыка внутри пакета. Структура: skills/имя-пакета/SKILL.md плюс папка references/ для подробных справок. Файл SKILL.md начинается с YAML-блока (название, описание ситуаций применения), затем идёт пронумерованный список правил для агента.
2. Опубликуйте пакет обычным способом. После npm install каталог skills/ окажется в node_modules/ рядом с исходниками. Никаких дополнительных действий при публикации не нужно.

3. Подключите навык к агентской среде через символическую ссылку. Для Codex (агентская среда OpenAI) команда выглядит так: mkdir -p .agents/skills ln -s ../../node_modules/@vendor/package/skills/skill-name .agents/skills/skill-name Ссылку можно сохранить в Git. После клонирования репозитория и npm install конфигурация восстановится на любой машине.

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

Установка пакета с навыком не меняет конфигурацию агента автоматически. Проект сам решает, какие навыки подключить. Git фиксирует, какие навыки активны, а package-lock.json фиксирует версии пакетов с этими навыками.

Есть ли аналог для тех, кто работает с российскими инструментами?

Формат Agent Skills привязан к экосистеме npm (менеджер пакетов для JavaScript и TypeScript). В российских ИИ-платформах, таких как YandexGPT и GigaChat, аналогичного механизма доставки инструкций через пакетный менеджер пока нет. Обе платформы поддерживают системные промпты (начальные инструкции, которые задают поведение модели), но не имеют стандарта для привязки инструкций к конкретной версии зависимости.

Если вы пишете на JavaScript или TypeScript и используете любой кодовый агент, Codex, Cursor, Cline, подход работает независимо от страны. Пакеты из npm доступны из РФ без ограничений.

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

Чем навык отличается от обычного README?

README написан для человека: он объясняет, что делает пакет, и показывает примеры. Навык написан для ИИ-агента: он задаёт порядок действий, указывает, какие контракты проверить, разделяет публичный API и внутреннюю реализацию, перечисляет запрещённые действия. Агенту не нужно «знакомиться» с пакетом, ему нужен чёткий протокол работы.

Не сломает ли подключение навыка мой проект?

Нет. Установка пакета с навыком ничего не меняет в конфигурации агента автоматически. Пока вы не создадите символическую ссылку в каталоге .agents/skills/, агент даже не узнает, что навык существует. Подключение и отключение полностью в ваших руках.

Работает ли это только с Codex?

Формат Agent Skills открытый. Codex поддерживает навыки через символические ссылки в .agents/skills/. Другие агентские среды тоже работают с этим форматом, но используют собственные каталоги обнаружения. Сам навык, это обычные файлы в пакете, и любой агент, умеющий читать файловую систему, может их использовать.