Custom skills як workflow-артефакти

1. Повторюваний prompt починає заважати

Зазвичай усе починається дуже безневинно. Один раз вдало сформулювали запит. Другий — скопіювали із нотаток. Третій — зберегли в final_prompt.md із припискою «не видаляти, це важливо». І в якийсь момент стає зрозуміло: це вже не разова репліка, а процедура, що кочує між людьми та сесіями.

Погляньте на три схожі запити:

Прочитай issue і оформи task spec: мета, scope, non-goals, критерії приймання.

Розбери баг-тикет і підготуй TASK_SPEC.md. Код поки не змінюй. Потрібні ризики та перевірка.

Поглянь на вхідний issue, постав уточнювальні запитання і перетвори його на заплановану задачу з планом перевірки.

Ззовні здається, що це три різні запити. Усередині — одне: взяти сирий issue і перетворити на структурований вхід. І щойно схема повторюється, памʼять уже не допомагає, а заважає. Забули non-goals. Не попросили план перевірки. Не проговорили «код поки не змінювати».

Skill з’являється не заради відчуття просунутості. Він потрібен саме тут: коли повторюваний prompt перестав бути шпаргалкою і став неоформленим шматком командної памʼяті.

2. Skill не замінює CLAUDE.md і не дублює rule

Тут достатньо однієї межі, але її постійно плутають. У цих механізмів різна робота, навіть якщо зовні все виглядає як «ще трохи тексту для Claude».

Prompt

CLAUDE.md

Rule

Skill

Якщо придивитися, CLAUDE.md і rule утримують постійні обмеження: перше — на весь проєкт, друге — на конкретну зону. Prompt живе одну задачу. Skill — там, де потрібно однаково відтворювати процедуру з упізнаваним входом і виходом: перетворювати issue на TASK_SPEC.md без переходу до реалізації.

Якщо у вас є фраза «не чіпай .env» — це правило. «Завжди показуй tests run» — загальне очікування проєкту. Skill починається там, де зʼявляється послідовність дій і перевірюваний результат.

3. Ознаки того, що prompt час піднімати до skill

Щойно ця межа стала зрозумілою, питання одразу стає практичним: чи час взагалі оформлювати процедуру як skill, чи вона ще занадто розмита? Робоча відповідь проста: skill варто робити, коли в процедури вже є повторюваний вхід, зрозумілий вихід і спосіб перевірки. І тут легко впасти в дві крайнощі: копіювати все вручну, доки не накопичиться кладовище однакових текстів, — або піднімати до skill будь-який вдалий запит і отримати гараж, де лежить усе, а знайти не можна нічого.

Тут корисно дивитися на чотири ознаки. Не як на бюрократичний чек-лист, а як на здоровий глузд.

Розберімо це на простому прикладі «так». Тричі за тиждень розбирали баг-тикети і хотіли один і той самий артефакт — TASK_SPEC.md із goal, scope, non-goals, constraints і планом перевірки. Вхід — issue-текст і пара посилань на файли. Вихід стабільний, вхід стабільний, підсумковий файл ви читаєте і перевіряєте. Готовий кандидат.

А тепер протилежний приклад «ні». Припустімо, ви «іноді просите Claude допомогти подумати про архітектуру». Звучить схоже на процедуру, але щоразу інший контекст, масштаб і тип результату: де список ризиків, де порівняння варіантів, де просто обговорення. Упакуєте в один skill — отримаєте універсальний ключ, який жодні двері нормально не відчиняє.

Є ще один важливий маркер-обманка: якщо ви щоразу переписуєте половину вихідного запиту, це не «skill потрібен терміново». Частіше стійкої процедури ще немає — а skill не маскує невизначеність, він працює там, де процедура вже усталилася.

Можна запамʼятати дуже приземлене правило: якщо prompt кочує між вами та колегами частіше, ніж пароль від офісного Wi‑Fi, час замислитися про skill. Формулювання не академічне, зате запамʼятовується.

4. Skill — це маленький інженерний контракт

Фраза «reusable workflow asset» звучить трохи пафосно, а по суті все доволі просто: skill відповідає на пʼять базових запитань. Коли використовувати? Що подати на вхід? Що вважати готовим результатом? Що робити не можна? Як перевірити, що спрацювало?

Ось мінімальна форма такої логіки:

# issue-analysis

Коли використовувати: коли вхідний issue потрібно перетворити на структурований TASK_SPEC.md
Вхід: текст issue, посилання на релевантні файли, за потреби логи
Результат: заповнений TASK_SPEC.md
Не можна: починати реалізацію, змінювати код, розширювати scope без причини
Перевірка: у специфікації є мета, межі, критерії приймання і план перевірки

Зверніть увагу: тут немає метаданих, полів чи налаштувань виклику — і це нормально. Якщо ви не можете людською мовою пояснити, коли застосовувати навик, який у нього вхід і вихід, жоден красивий SKILL.md вас не врятує.

Є корисна аналогія з функцією в коді. Її відрізняє не назва, а контракт: входи, вихід, побічні ефекти, обмеження. З skill так само — тільки замість суми ви отримуєте робочий результат.

Саме тому skill не можна проєктувати як «величезний текст на всі випадки життя». Інструкції, чек-лист, шаблон, пара прикладів — усе обслуговує одну процедуру. Засунете туди аналіз, реалізацію, ревʼю та оновлення документації — навик стане маленьким театром одного актора, який робить усе одразу і тому все посередньо.

У хорошій команді skill починають розглядати майже як код: у нього є власник, його можна відкрити, обговорити, покращити.

5. Skill issue-analysis для Commerce OS

Тепер давайте приземлимо все це на наш наскрізний проєкт. Є Workflow Kit як метапроєкт і Commerce OS як робоча кодова база, куди прилітають баги, фічі та дрібні задачі. Одна з найповторюваніших процедур — розбір вхідного issue до початку кодування.

flowchart LR
    A[Вхідний issue] --> B[Навик issue-analysis]
    B --> C[TASK_SPEC.md]
    C --> D[Перевірюваний план роботи]

Тут важливий не синтаксис виклику і не розташування папок, а контракт результату: на вході сирий issue, на виході перевірюваний TASK_SPEC.md. Відтворюється однаково — отже, це не вдалий prompt, а reusable workflow.

Візьмемо приклад issue з Commerce OS. Припустімо, підтримка скаржиться, що refund-запити в inbox показуються не за порядком. Сирий текст:

Баг: у support inbox refund-запити іноді відображаються не за часом надходження.
Симптом: оператор бачить старіші заявки вище за нові.
Очікування: нові refund-запити мають бути зверху.
Важливо: не змінювати весь workflow refund approval.

Результат може починатися так:

## Мета
Виправити сортування refund-запитів у support inbox так, щоб нові заявки відображалися вище за старі.

## Область змін
Модулі inbox і пов’язані тести сортування.

## Не-цілі
Не змінювати логіку refund approval і бізнес-правила оброблення повернень.

## Перевірка
Перевірити тести inbox і ручний сценарій сортування на нових і старих заявках.

Цього прикладу вже достатньо, щоб побачити, навіщо потрібен skill. У людини — документ, який можна переглянути до реалізації. У Claude — чітка межа. У команди — повторюваний стандарт.

Саме тут важливо розуміти: цінність skill у тому, що він вчасно зупиняється. Полізе issue-analysis редагувати код — змішає кілька процесів; перевіряти таку суміш складніше. Тому хороша перша версія скромна. Скромно? Так. Корисно? Дуже. І відтворювано.

У цьому місці особливо добре видно, як skill спирається на пройдений матеріал курсу. Він не вигадує методику — упаковує знайомі речі: мета, current vs desired behavior, scope, non-goals, критерії приймання, план перевірки.

6. Рівні життя skill у Workflow Kit

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

Якщо ви лише пробуєте нову ідею — не тягніть її одразу до спільного Workflow Kit. Це приблизно як комітити в main перший-ліпший чорновик. Спочатку навик доводить, що економить час і стабілізує результат, — потім іде на рівень проєкту та на review.

Дуже корисно памʼятати і зворотний бік. Не кожен повторюваний текст заслуговує на життя в репозиторії. Іноді достатньо оновити CLAUDE.md, іноді логічніший локальний rule, іноді чесніше залишити звичайний prompt. Workflow Kit сильний не кількістю артефактів, а тим, що кожен відповідає на реальний, повторюваний біль.

І ось тут skill раптом стає не зручністю, а елементом командної культури. Замість «попросіть у Петі, у нього хороший prompt» команда отримує навик, який можна відкрити, перевірити і покращити. Не особиста магія, а спільна інженерна памʼять. А коли такі шматочки памʼяті збираються в одному місці, Workflow Kit перестає бути папкою «щось про Claude» і стає справжнім робочим інструментом.