Как разделить большой SKILL.md на references, scripts и assets

Когда SKILL.md действительно пора разделять?

Разделяйте SKILL.md, когда основной маршрут теряется среди справочников, примеров и повторяющегося кода, а для большинства запусков нужен лишь небольшой фрагмент. Порог около 500 строк служит ориентиром качества, а не формальным пределом валидности.

После срабатывания навыка основной SKILL.md загружается целиком. Поэтому каждая лишняя инструкция конкурирует с задачей, историей диалога и другими правилами. Физический размер важен, но главный признак перегруза проще: агенту трудно понять обязательный путь без чтения материала, который нужен лишь иногда.

Как измерить фактическую загрузку и стоимость, описано в статье как Agent Skills расходуют контекст и токены. Здесь мы меняем архитектуру файла, а не считаем токены.

Что должно остаться в основном SKILL.md?

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

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

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

Как быстро решить, куда перенести каждый раздел?

Классифицируйте содержимое по роли: обязательный маршрут остаётся в SKILL.md, условные знания идут в references, повторяемая детерминированная операция становится script, а файл для конечного результата относится к assets. Дубли и вводные пояснения удаляются.

Что переносить в references?

В references переносят подробные политики, схемы, API-справочники, платформенные варианты и большие примеры, которые нужны только для части задач. Каждый файл должен иметь понятное имя, узкую тему и прямое условие чтения в SKILL.md.

Делите справочники по ситуации или домену: security-review.md, provider-openai.md, provider-anthropic.md. Один огромный REFERENCE.md часто лишь переносит исходную проблему в другую папку.

Когда инструкция должна стать скриптом?

Превращайте шаг в script, когда одна и та же логика повторяется, должна давать одинаковый результат и легко проверяется машиной. Скрипт должен быть неинтерактивным, иметь понятные аргументы, полезные ошибки и компактный вывод.

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

Для операций с риском полезен отдельный validator. Его устройство разобрано в статье как добавить самопроверку в Agent Skill.

Что относится к assets?

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

Простой тест: если файл нужно понять и применить как знание, это reference. Если файл нужно скопировать, заполнить или встроить в итог, это asset. Для шаблона полезно отдельно описать в SKILL.md, когда его брать и какие поля нельзя удалять.

Как спроектировать новое дерево файлов?

Сначала нарисуйте дерево по ролям, затем добавьте прямые ссылки из SKILL.md ко всем условным материалам. Избегайте глубоких цепочек, при которых основной файл отправляет в один справочник, а тот скрыто отправляет ещё в несколько.

1. 1. Снимите baseline

   Сохраните результаты прямого, пограничного, отрицательного и ошибочного сценариев.

2. 2. Разметьте содержимое

   Пометьте каждый раздел как core, reference, script, asset или delete.

3. 3. Сократите ядро

   Оставьте один маршрут, gates и условия выбора веток.

4. 4. Создайте узкие файлы

   Разделите знания и операции по назначению, а не по случайному числу строк.

5. 5. Добавьте карту

   Для каждого пути укажите точное условие чтения, запуска или использования.

Почему ссылки должны идти прямо из SKILL.md?

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

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

Как проверить поведение после разделения?

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

• Навык по-прежнему выбирается для прямого запроса.
• Критические правила выполняются без чтения необязательных файлов.
• Нужный reference открывается только в своей ветке.
• Все scripts завершаются с ожидаемыми кодами.
• Результат baseline не ухудшился по обязательным критериям.

Команда skills-ref validate проверяет базовый формат и соглашения имени. Она не подтверждает, что новая карта файлов сохранила поведение, поэтому после статической проверки нужен реальный прогон.

Автоматизировать этот набор поможет инструкция как проверять Agent Skills в CI.

Какие ошибки ломают механическое разделение?

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

• Считать 500 строк жёстким техническим лимитом.
• Выносить обязательные подтверждения из основного файла.
• Требовать читать все references в каждом запуске.
• Хранить документацию в assets.
• Оставлять длинный повторяющийся код в SKILL.md.
• Делать scripts интерактивными и зависимыми от одной машины.
• Смешивать несколько несвязанных процессов вместо создания отдельных skills.

Если skill стал большим из-за двух разных намерений, папки не решат проблему. Разделите его на два навыка с узкими descriptions и отдельными тестами срабатывания.