Package skills в Dart: как передать AI-агенту знания о библиотеке

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

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

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

Package skills в Dart позволяют поставлять подобные инструкции вместе с библиотекой. Разработчик может установить их в проект, чтобы агент получал необходимые рекомендации через поддерживаемый им механизм skills. Возможность интересна не только для ускорения написания кода. Она ставит практический вопрос: что происходит с такими инструкциями после обновления зависимости или появления собственных правил команды?

Что именно получает агент

Skill — это набор инструкций для определённого класса задач. Обычно он содержит описание назначения, правила работы и примеры; подробные материалы могут находиться рядом, в отдельных файлах. Package skill отличается источником: его распространяет автор Dart-пакета вместе с библиотекой.

Это не новая возможность исполняемого приложения. Skill не добавляет метод в класс и не переобучает модель. Он предоставляет текст и связанные материалы, которые агент может использовать при работе. Как именно они обнаруживаются и подключаются к задаче, зависит от инструмента, в котором работает агент. Документация Dart описывает установку таких материалов в каталоги поддерживаемых агентских инструментов.

У skill есть основной файл SKILL.md. В его начале задаются имя и описание: для каких задач предназначены инструкции. Затем идёт обычный Markdown. Автор пакета размещает такие каталоги внутри skills/ рядом с исходниками библиотеки. Руководство для авторов пакетов описывает структуру и требования к именованию.

Условная структура небольшого пакета выглядит так:

sample_package/
  pubspec.yaml
  lib/
  skills/
    sample-package-usage/
      SKILL.md
      references/
        examples.md

Здесь важно назначение материала, а не количество файлов. Десять страниц универсальных советов о «качественном коде» мало помогают выбрать правильный способ вызова конкретной библиотеки. Полезная инструкция объясняет, когда её применять, какое решение требуется принять и где проверить детали API.

Чем это отличается от документации

API-документация отвечает на вопросы о доступных типах, параметрах и контрактах методов. Руководство помогает человеку пройти сценарий: подключить библиотеку, выполнить операцию, обработать результат. Skill может собрать необходимые указания для агента: с какого раздела начать, какие ограничения проверить и какой пример использовать для данной задачи.

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

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

Для библиотек, разделяющих такие обязанности, инструкция может объяснить порядок их применения. Конкретный пример — ark_mvp из экосистемы ArkTelos. Пакет отделяет готовое состояние представления от временных действий интерфейса. Последние называются ViewEffect: они передаются без хранения и повторного воспроизведения. Поэтому информацию, которая должна сохраниться до следующего открытия экрана, нельзя оставлять только в таком эффекте.

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

Это пример содержания возможной инструкции, а не объявление готового skill для ark_mvp. В эксперименте ниже библиотека не используется: проверяется механизм сопровождения инструкций, независимо от их архитектурного содержания.

Пакет skills не равен самим skills

Для установки инструкций в Dart есть отдельный инструмент командной строки — skills. Совпадение названий несколько мешает первому знакомству: skills — это материалы, а пакет skills помогает ими управлять.

Обычный pub get разрешает зависимости приложения. Это ещё не означает, что инструкции из этих зависимостей установлены для агента. Для них выполняется отдельная операция. В документации показана такая точка входа:

dart run skills@ get

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

В эксперименте использовалась точно закреплённая версия skills 1.0.1. Она запускалась напрямую из отдельного служебного Dart-пакета с сохранённым pubspec.lock — файлом с разрешёнными версиями зависимостей. Приведённая выше краткая команда не воспроизводит это закрепление сама по себе.

Для установки был выбран адаптер generic: установленная инструкция попадала в .agents/skills/. Рядом инструмент вёл собственный учёт установленных материалов. Иными словами, после установки в проекте появлялась копия инструкции, а не постоянно читаемая ссылка на файл внутри зависимости.

Именно у этой копии затем возникает собственная история изменений.

Небольшой эксперимент вместо предположений

Для проверки подготовлен пакет lab_skill_fixture с двумя редакциями инструкции: A и B. В них различается текст. Есть также вспомогательный файл, отдельная зависимость для разработки и транзитивная зависимость — пакет, который подключён через другой пакет, а не непосредственно приложением. В каталог назначения добавлен и файл, которым инструмент не управляет.

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

Проверка выполнена на Dart SDK 3.13.2 в Linux arm64, внутри изолированного контейнера. Двенадцать сценариев запускались по два раза на одном собранном образе; команды, состояния файлов и ответы в диалогах сохранены. Сравнение подтвердило одинаковые результаты. При повторной установке без изменений содержимое осталось прежним, но обновилось служебное время установки — это поле сравнивалось отдельно от содержательных данных.

Исходники и порядок воспроизведения собраны в эксперименте package-skills-workflow, а границы проверки — в протоколе результатов. Далее важны три ситуации, которые легко встретить в обычном проекте.

Когда инструкция обновилась, а команда уже дописала своё

Сначала установлена редакция A. Затем в её установленную копию добавлена локальная правка. В реальном проекте так могла бы появиться договорённость команды: использовать принятый способ обработки ошибок или не менять выбранную организацию модулей.

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

Теперь у инструмента две расходящиеся редакции: новая от автора пакета и локальная с изменениями команды. В интерактивном режиме он показал установленный skill с пометкой Local edits, не выбрав его для обновления по умолчанию.

Подтверждение пустого выбора сохранило локальные байты. Явный выбор skill заменил их редакцией B. Автоматического объединения двух текстов в этом сценарии не происходило.

Разница существенная. Сохранить локальную версию — значит также оставить её без изменений из новой редакции автора. Заменить — значит потерять добавленные правила. Если нужны обе части, требуется сопоставить тексты и принять решение, а не просто выбрать более удобную кнопку.

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

Что меняет --all

Для автоматизации предусмотрен флаг --all. В проверке он применялся к выбранному пакету, чтобы обновить его skills без ручного выбора. Исходный конфликт был тем же: локально изменённая A и новая редакция B в зависимости.

В skills 1.0.1 этот вызов заменил локальную инструкцию редакцией B без диалога.

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

Перед добавлением команды в скрипт обновления нужно ответить на простой вопрос: кто владеет содержимым установленных файлов? Если автор пакета — обновление должно возвращать его редакцию. Если команда тоже меняет эти файлы, требуется сохранение истории и просмотр различий. Сам флаг не может решить это за проект.

Наблюдение ограничено конкретным конфликтом и версией инструмента. Оно не означает, что --all устраняет любые возможные запросы подтверждения при любых источниках. В частности, отдельные Git-источники в этот опыт не входили.

Библиотеку удалили. Что осталось у агента?

Следующая ситуация возникает при замене зависимости. Пакет удалён из pubspec.yaml, затем выполнен pub get. С точки зрения состава зависимостей работа закончена. Но установленная инструкция в проверке осталась на месте.

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

В отдельном сценарии их удалил prune --all. В другом — последующий get, который также выполнил очистку. Файл, добавленный вручную и не управляемый инструментом, сохранился. Выборочное удаление одного skill также не затронуло установленную инструкцию другой зависимости.

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

Что имеет смысл взять в свой проект

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

Для автора библиотеки отправная точка похожая: выбрать типичный неверный способ использования и объяснить нужное решение. Например, в случае с ark_mvp — сначала разобрать, какая информация должна сохраняться, а какое действие адресовано только активному интерфейсу. Общий призыв «соблюдать архитектуру» здесь слабее конкретного ограничения, связанного с контрактом библиотеки.

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

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

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

---

Другие инженерные разборы — в ArkTelos Lab. Пакеты и новости проекта — на официальном сайте ArkTelos.

Каналы: Lab RU | Lab EN | ArkTelos RU | ArkTelos EN.