skill-quality — як писати скіли

Скіл існує, щоб вичавити передбачуваність із випадкової системи. Передбачуваність — це однаковий процес щоразу, а не однаковий текст на виході. Усе нижче служить їй.

Дві ціни

Кожен скіл коштує однією з двох валют — і вибір валюти робиться в заголовку файлу:

Скілів «тільки руками» стало більше, ніж пам'ятаєш → лікується скілом-маршрутизатором: один скіл, який перелічує решту й каже, коли що брати (у тебе це cheatsheet-advisor).

Опис — це тригери, не візитівка

Опис робить одну роботу: щоб скіл спрацював. Кожне слово коштує контексту, тож опис ріжеться жорсткіше за тіло.

• Головне слово — на початок. Саме там воно ловить.
• Один тригер на гілку. «будує фічі через TDD… просить тести спершу» — це одна гілка, написана двічі. Схлопни.
• Не переказуй, що скіл робить — це вже в тілі. В описі лише «коли брати».
• Назви й антигілку, якщо поруч є схожий скіл: «не для X — там інший скіл». Інакше чіплятимуться обидва.

Сходинки: що куди класти

Матеріал скіла — це кроки (що робити по черзі) і довідка (правила й факти). Три сходинки за терміновістю:

1. Крок у SKILL.md — дія в порядку. Кожен крок закінчується критерієм завершення: умовою, за якою видно, що готово. Критерій має бути перевірним («усі змінені моделі враховано»), а не «зроби добре» — розмитий критерій запрошує кинути на півдорозі.
2. Довідка в SKILL.md — правило, яке читають на вимогу. Плаский список правил — це нормально, не запах.
3. Довідка у файлі поруч — винесене з SKILL.md у сусідній файл, куди веде вказівник. Вантажиться, лише коли вказівник спрацював.

Виніс замало — верх роздувся; виніс забагато — сховав потрібне. Проба проста: що потрібне кожному проходу — лишається в SKILL.md; що потрібне лише деяким — за вказівник.

Третій шар: tools/

Опис + інструкція — це ще не скіл, це промпт. Сила — у tools/: скрипти, шаблони, готові компоненти.

Можна кодом — роби кодом. Повторювана логіка у вигляді скрипта виконується стабільно і коштує 0 токенів. Та сама логіка, яку модель генерує щоразу заново, коштує тисячі токенів і щоразу трохи інша.

Приклади: шаблон документа, готовий React-компонент, скрипт-перевірка, few-shot еталон у examples/.

Провідні слова

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

Працює двічі: в тілі задає однакову поведінку щоразу, а в описі — ловить виклик, бо ти те саме слово вживаєш у своїх промптах.

Шукай, що схлопнути:

• «швидкий, передбачуваний, без накладних» → тугий (тугий цикл).
• «цикл, якому ти віриш» → червоний (цикл або червоніє на баг, або ні).

Шість способів зіпсувати скіл

Коли різати на два скіли

Кожен розріз коштує однієї з двох цін, тож ріж, лише коли розріз це відпрацьовує:

• За викликом — коли в частини є власне головне слово, за яким вона має чіплятися окремо, або інший скіл має до неї дотягнутися.
• За послідовністю — коли кроки попереду видно, і вони спокушають кинути поточний недоробленим. Прибери їх з очей.

Ритуал наприкінці сесії

Скіл працював у сесії → спитай користувача: «що забрати у скіл назавжди, а що разова правка?» Дивись, що він правив руками і що пояснював удруге — це і є кандидати в SKILL.md чи tools/. 30 секунд — і наступна сесія розумніша.

Шаблон нового скіла: tools/SKILL-template.md.