Когда ИИ-агент сталкивается с незнакомой библиотекой, он обычно исследует установленный пакет: находит точку входа, читает типы и исходный код, ищет README, примеры и тесты. Так можно разобраться практически с любой зависимостью.

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

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

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

Один из вариантов — включить навык в npm-пакет:

package 2.4
├── code 2.4
└── skill 2.4

Менеджер пакетов установит код и навык одновременно. Агент получит компактное описание библиотеки рядом с её исходниками, а версия инструкций будет соответствовать версии пакета.

Что такое Agent Skill

Agent Skills — открытый формат инструкций для ИИ-агентов. В простейшем случае навык (skill) представляет собой каталог с файлом SKILL.md:

package/
├── src/
├── types.d.ts
└── skills/
    └── package-name/
        ├── SKILL.md
        └── references/

SKILL.md содержит YAML-метаданные и инструкции. Рядом могут находиться справочные материалы, примеры и скрипты.

Обычно навыки описывают самостоятельные рабочие процессы: подготовку релиза, проверку изменений в pull request или развёртывание приложения. Тем же способом можно описать и программную зависимость.

Навык внутри пакета может объяснить агенту:

• назначение компонента и его публичные границы;

• правила подключения;

• принятые соглашения;

• стабильные и внутренние API;

• порядок проверки результата;

• действия, которые нельзя выполнять без явного разрешения.

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

Как выглядит реальная инструкция

В пакете @teqfw/db, например, файл навыка начинается с описания ситуаций, в которых его нужно использовать:

---
name: teqfw-db
description: Use this skill when integrating, configuring, using,
  testing, reviewing, or modifying JavaScript modules that consume
  @teqfw/db.
---

Затем идёт краткий порядок работы с пакетом. В сокращённом виде он выглядит так:

1. Compose the package through the published `TeqFw_Db_` DI namespace;
   do not import `@teqfw/db/src/**` as a public API.
2. Load configuration sources before resolving database components.
3. Pass an outer transaction when several operations share one atomic boundary.
4. Never finalize caller-owned transactions from nested operations.
5. Never infer renames, conversions, cutover, or source deletion during rebuild.
6. Verify exact tokens and callable shapes against the installed package version.

Помимо возможностей базы данных, такая инструкция описывает допустимые действия агента.

Например, наличие реализации в src/ не делает её публичным API. Внешняя транзакция принадлежит вызывающему коду, поэтому вложенная CRUD-операция не должна выполнять commit. При пересборке базы агент не должен самостоятельно предполагать переименования полей, считать пересборку принятой владельцем системы или удалять исходные данные.

Подробности вынесены в references/: отдельно описаны модель данных, подключение, публичные контракты и распространение навыка. Агент обращается к этим материалам по мере необходимости, а не загружает все инструкции заранее.

Поставка заодно связывает инструкции с версией кода

Если каталог skills/ входит в npm-артефакт, после установки он оказывается рядом с кодом:

node_modules/@teqfw/db/
├── src/
├── types.d.ts
└── skills/
    └── teqfw-db/
        ├── SKILL.md
        └── references/

Версию пакета фиксирует package-lock.json:

package-lock.json
        ↓
@vendor/package 2.4
├── code 2.4
└── skill 2.4

При обновлении зависимости обновляется и навык. При откате возвращаются инструкции предыдущей версии.

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

Навык не заменяет публичные контракты, исходный код и тесты. Он сообщает, где их искать, как отличать публичный API от деталей реализации и что именно следует проверить для текущей задачи.

Поставка и подключение — разные действия

Сам факт установки пакета не должен автоматически менять конфигурацию агента в приложении.

Зависимость может содержать навык:

node_modules/@teqfw/di/skills/teqfw-di

Но проект сам решает, нужно ли делать этот навык доступным агенту.

В Codex его можно явно подключить через символическую ссылку:

mkdir -p .agents/skills

ln -s \
  ../../node_modules/@teqfw/di/skills/teqfw-di \
  .agents/skills/teqfw-di

Git и lock-файл фиксируют разные решения:

Git
    → какие навыки подключены к проекту

package-lock.json
    → какие версии пакетов с этими навыками установлены

Ссылку .agents/skills/teqfw-di можно сохранить в Git. После получения репозитория и выполнения npm install та же конфигурация восстановится на другой машине.

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

Codex поддерживает навыки, подключённые через символические ссылки. Другие агентские среды тоже работают с форматом Agent Skills, но используют собственные каталоги обнаружения. Пакет содержит навык, а проект подключает его способом, принятым в выбранной среде.

Почему не стоит подключать все навыки автоматически

В большом Node.js-приложении могут быть сотни прямых и транзитивных зависимостей. Наличие пакета в node_modules ещё не означает, что его инструкции нужны агенту.

Автоматическое подключение всех найденных навыков создаёт несколько проблем:

• растёт список доступных инструкций;

• пересекаются области ответственности пакетов;

• транзитивная зависимость получает возможность влиять на работу агента;

• владельцу проекта сложнее понять, какими правилами руководствовался агент при изменении кода.

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

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

Реализация в TeqFW

Я применяю эту схему в Tequila Framework (TeqFW). Это набор npm-пакетов для модульных JavaScript-приложений.

Навыки уже входят в следующие платформенные пакеты:

@teqfw/di           → teqfw-di
@teqfw/cfg          → teqfw-cfg
@teqfw/cli          → teqfw-cli
@teqfw/log          → teqfw-log
@teqfw/db           → teqfw-db
@flancer32/teq-web  → teqfw-web

Каждый навык описывает только свой пакет. teqfw-di объясняет модель связывания модулей и правила работы с DI-контейнером. teqfw-cfg описывает источники и жизненный цикл конфигурации. teqfw-db задаёт границы работы с распределённой моделью данных, SQL-диалектами, транзакциями и пересборкой базы. teqfw-web описывает серверный конвейер запросов и статические ресурсы.

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

В результате у одного программного компонента появляется несколько форм представления, каждая для своего адресата:

исходный код       → исполняемая среда
JSDoc и types.d.ts → IDE и статический анализ
README             → разработчик
SKILL.md            → ИИ-агент

Они относятся к одной версии компонента и выпускаются вместе.

Ограничения подхода

Навык, поставляемый вместе с пакетом, не гарантирует предсказуемого результата.

Остаются ограничения:

• агент может неверно понять или не применить инструкцию;

• автор пакета может забыть обновить навык вместе с API;

• фактическое поведение по-прежнему определяют код и тесты;

• разные агентские среды по-разному находят и подключают навыки;

• навык из сторонней зависимости нельзя подключать без проверки;

• слишком большой навык расходует контекст модели и затрудняет поиск нужного правила.

Поэтому навык стоит рассматривать как ещё одну часть пакета, а не как замену документации, типов или тестов.

Практичнее держать SKILL.md коротким: описать область применения, основные запреты и порядок чтения. Детали можно вынести в тематические файлы, к которым агент обратится, когда они понадобятся.

Связанные инициативы

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

В репозитории Agent Skills есть RFC о распространении навыков через npm-пакеты. Проект skills-npm исследует поиск навыков внутри установленных зависимостей и их подключение к разным агентским средам.

Рабочее название, которое я использую для этой схемы, — Dependency-bound Agent Skills: навыки агентов, связанные с программными зависимостями и их версиями. Это не название стандарта, а описание модели распространения.

Вывод

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

Менеджер пакетов уже умеет устанавливать нужную версию кода и воспроизводить ту же установку на другой машине. В пакет можно включить и инструкции для ИИ-агента.

Тогда:

• автор библиотеки компактно описывает назначение, границы и правила работы с компонентом;

• npm устанавливает это описание вместе с кодом;

• lock-файл фиксирует версию пакета, в котором находятся и код, и инструкции;

• проект выбирает, какие навыки подключить;

• агент получает локальные инструкции для реально установленной зависимости.

Для TeqFW навык стал ещё одной частью программного пакета. Код нужен исполняемой среде, типы — IDE, README — разработчику, а SKILL.md — ИИ-агенту.

Ссылки

• Agent Skills

• Agent Skills Specification

• OpenAI Codex: Agent Skills

• RFC: Standardize npm/JavaScript Package Distribution

• npm-based Agent Skills Convention

• skills-npm