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> # must equal the directory name
description: <1-2 sentence summary an agent uses to decide whether to load>
---
name і description несуть основне навантаження. Усе інше вкладається в блок metadata: з yfm як скаляри, розділені комами — необов'язково, але це додає структуру для індексації, пошуку та онтологічних гачків.
Підфайли не несуть YFM. Лише SKILL.md фільтрує завантажувач, тому тільки він потребує фронтматтеру. Кожен інший файл (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, docs index) та useful links (точенкові посилання на ті 20% документів, які покривають 80% випадків використання). Спершу перелік root, потім useful — AI розуміє порядок. Без дублювання, якщо наголос не критичний.
М'які застереження (судження)
- Підфайли (CLEANUP.md, references/*) можуть бути довшими за SKILL.md, але перші 20 рядків і далі несуть основне навантаження (та сама піраміда).
- МУСИТЬ посилатися на кожен підфайл із батьківського SKILL.md (пряме посилання обов'язкове). Зворотне посилання на батьківський SKILL.md із підфайлу є необов'язковим — файли usecase посилаються на батьківський неявно через свій шлях. Забезпечується правилом
sw-1000-no-orphan-docsу skill0-writer.rule.yml. - Припущення — викладайте перевірені факти або позначайте їх як «untested».
- Емодзі — окрім випадків, коли тема skill-у цього вимагає.