x-skill-bundles

name	x-skill-bundles
description	Применяй вместе с `skill-creator`, когда создаёшь или редактируешь локальный skill в `level85`: project-specific требования к `SKILL.md`, `scripts/`, `assets/`, аудируемости и запрету ссылок на эталонные репозитории

Skill Bundles

Этот скилл не заменяет skill-creator, а уточняет его для level85.

Используй его вместе с skill-creator, когда:

• создаёшь новый локальный skill в .agents/skills/
• перерабатываешь существующий локальный skill bundle
• решаешь, что оставить в SKILL.md, а что вынести в scripts/ или assets/

Главный принцип

SKILL.md должен оставаться главным человеком-читаемым источником правил и workflow.

Если важную часть skill больше нельзя быстро проверить глазами по SKILL.md и bundled resources, bundle спроектирован плохо.

Как раскладывать содержимое

• SKILL.md держит всё: условия срабатывания, workflow, правила выбора, границы применения, примеры кода и детали
• assets/ держит прозрачные шаблоны и заготовки, если важен сам вид результата
• scripts/ допустимы только для коротких, детерминированных и легко аудируемых операций

Всё содержание skill должно быть в SKILL.md. Вынос деталей и примеров в отдельные файлы (references/) запрещён — агент может не загрузить их и сгенерировать код, игнорируя project conventions.

Правила для scripts/

• для простых shell-oriented действий предпочитай sh
• переходи на py только когда shell заметно ухудшает читаемость или надёжность
• если задачу можно надёжно описать двумя-тремя абзацами или коротким reference, предпочитай текст, а не script
• если важен сам шаблон результата, предпочитай assets/, а не генераторный script
• генераторные scripts по умолчанию нежелательны; если прозрачность можно сохранить через assets/ + ручную подстановку, выбирай этот путь
• script не должен прятать важную проектную логику, которую пользователь больше не может быстро проверить глазами
• script должен оставаться маленьким, прозрачным и опциональным: он помогает выполнить skill, но не подменяет его смысл
• script не должен быть “магией”: перед запуском пользователь должен понимать, что он проверит, создаст или изменит
• для skill scripts предпочитай размер порядка ~100 строк или меньше; если script заметно растёт, это сигнал вынести логику обратно в SKILL.md или assets/
• каждый skill script должен начинаться с короткого заголовка: что делает, какие аргументы принимает, что проверяет или создаёт и что не делает
• в SKILL.md для каждого script должен быть короткий пример вызова и понятное объяснение, что именно он проверяет или генерирует

Источники истины

Skill bundles не должны ссылаться на эталонные репозитории как на внешние источники истины.

Если пример из эталона полезен:

• вбери паттерн в сам skill bundle
• оформи его как локальный пример, reference или asset
• не оставляй ссылку на эталон как на обязательный внешний контекст

Допустимые project dependencies для skills — только реальные рабочие контракты на ../adapters и ../platform, если skill описывает совместимость с ними.

Критерий оправданности skill

Skill оправдан, если описывает API или паттерн, которого нет в публичной документации.

Если информация доступна через go doc, README библиотеки или стандартную практику Go — это не skill, а пересказ документации. Пересказ замусоривает контекст и устаревает быстрее оригинала.

Тест: «если удалить этот skill, сгенерирует ли LLM неправильный код при работе с этим проектом?» Если ответ «нет» — skill не нужен. Допустимый минимум — appendix из 3-5 project-specific дельт.

Проверка качества

Перед завершением работы над skill bundle проверь:

• SKILL.md читается сам по себе и не превращён в оглавление без содержания
• все детали и примеры кода находятся в SKILL.md, а не в отдельных файлах
• scripts, если они есть, прозрачны и опциональны
• важная логика не спрятана в generator script
• bundle не ссылается на эталонные репозитории как на внешний источник истины