skill0-writer
Документы skill0 следуют принципу пирамиды: агенты могут прочитать только первые 10–30 строк, поэтому самая важная информация должна быть в начале. Детали после строки 30 — бонус, а не основная нагрузка.
Что не ловят никакие правила
- Ясность важнее краткости. Короткий документ, дающий неправильный ответ, хуже длинного, дающего правильный.
- Предупреждения о безопасности ДОЛЖНЫ быть явными — используйте MUST, NEVER, DO NOT. Излагайте оговорки как полные утверждения, а не в скобках.
- Не разворачивайте общеизвестное. Если условного слова и пары предложений достаточно, остановитесь. Читатель уже знает, что такое YAML, git и кэш; тратьте контекст на то, что специфично для этого репозитория. Обычный виновник — обоснования: давайте причину правила только когда без неё оно кажется неверным. (
sw-1200) - Таблицы — только для настоящих матриц. 3+ столбцов, строки которых сопоставляются друг с другом. Двухколоночная таблица — список в обёртке таблицы — пишите список. Набор данных стоит выносить во внешний
.tsvрядом с документом, со ссылкой, чтобыx tsvмог его запрашивать. (sw-1250)
YFM — только SKILL.md
---
name: <slug> # должен совпадать с именем каталога
description: <краткое описание в 1-2 предложения, по которому агент решает, загружать ли>
---
name и description несущественны. Всё остальное вкладывается в блок metadata: из yfm как скаляры через запятую — необязательно и добавляет структуру для индексации, обнаружения и онтологических хуков.
Подфайлы не содержат YFM. Loader фильтрует только SKILL.md, поэтому frontmatter нужен только ему. Любой другой файл (references/*, usecase/*, EXAMPLE.md, *.report.md …) читается напрямую агентом, который уже решил его открыть, — YFM там это чистые затраты токенов, повторяющие назначение, уже данное заголовком и первой строкой. Начинайте эти файлы с заголовка #. Отступление требует указанной в самом файле причины.
Для китайских локализаций используйте параллельный SKILL.cn.md (по одному на skill). Не смешивайте языки в одном файле.
Механические проверки
Определены в skill0-writer.rule.yml. Запустите x rule lint skill0-writer.rule.yml и x rule check -r skill0-writer.rule.yml lib/skill0/. Покрытие: наличие YFM + полей name/description, формат name, число строк ≤ 100 (в идеале 50), порядок разделов install → usage → advanced → links, только английский, без вступления / без заключения / без повторов, без изолированных файлов.
Проверка безопасности при усечении
После написания остановитесь на строке 30: не сформирует ли агент, остановившийся здесь, неправильного понимания?
Если да, переместите критическое уточнение выше. Первые 30 строк должны давать верную (пусть и неполную) ментальную модель. После строки 30 расширяйте деталями — пирамида самокорректируется.
Двухслойная загрузка: description для сопоставления, body для справки
Загрузчики skills (Claude Code, Cursor, Continue и др.) загружают SKILL.md в два этапа:
- YFM
description:— автоматически загружается в каталог агента для сопоставления. Агент читает description, чтобы решить, загружать ли skill. - Body — загружается по запросу после сопоставления. Справочный материал.
Следствия:
- Description = что это + когда загружать — плотный по ключевым словам, богатый триггерами, сжатый.
- Body = как использовать + справка — примеры, схемы, граничные случаи, ссылки на более глубокие документы.
Не дублируйте содержимое между двумя слоями. Что бы description ни сообщал, body должен это развивать, а не повторять ту же поверхность. Первый абзац body особенно не должен перечислять те же особенности, что и description, — body начинается со справки, а не со второго резюме.
Практический тест: если полностью удалить description и прочитать только первые 30 строк body, агент всё равно должен видеть, что делает skill и когда его загружать. Если только description несёт эту информацию, body нечего добавить в начале — перенесите объяснение в body, а description оставьте с заголовком.
Skill — это пакет знаний, а не учебник
Тело skill — брифинг для LLM, а не курс для новичка.
- Способность живёт в LLM. Body не учит.
- Знание живёт в инструментах данных x-cmd (
x wkp/x rfc/x cve, NVD / MITRE / GHSA) и во внешних источниках. Body указывает; агент сам запрашивает. - Фрейминг — работа skill: называет форму задачи, соглашение, структурированный вывод, используемый инструмент x-cmd.
Skill несёт угол решения, соглашение, форму вывода и указатели на источники. Он не несёт способности (она уже есть у LLM), статические данные (устаревают) или учебники (используйте sidecar'ы).
Когда детали слишком конкретны или слишком актуальны, выносите их в sidecar (references/, ANALYTICS.md) или во внешний всегда обновляемый документ.
Внешние ссылки
Собирайте два типа: root links (точки входа вроде llms.txt, индекса документации) и useful links (точечные ссылки на 20% документации, покрывающие 80% случаев). Сначала root, затем useful — ИИ понимает порядок. Без дублирования, если только акцент не критичен.
Мягкие оговорки (оценочные суждения)
- Подфайлы (CLEANUP.md, references/*) могут быть длиннее SKILL.md, но первые 20 строк всё равно несут нагрузку (та же пирамида).
- ОБЯЗАН ссылаться на каждый подфайл из родительского SKILL.md (прямая ссылка обязательна). Обратная ссылка из подфайла на родительский SKILL.md необязательна — файлы usecase неявно ссылаются на родителя через свой путь. Обеспечивается правилом
sw-1000-no-orphan-docsв skill0-writer.rule.yml. - Спекуляции — формулируйте проверенные факты, либо помечайте «untested».
- Эмодзи — если только тема skill этого не требует.