SKILL.md: анатомія і виклик skill

1. Файл замість «ми й так пам’ятаємо»

Коли ви вперше вирішуєте оформити skill, спокуса велика: створити папку, кинути туди кілька розумних фраз, вирішити, що готово. Автор пам’ятає, що мав на увазі. Решта бачать папку із загадковою назвою і текстом рівня «допомагає з аналізом задач». Банка на кухні з написом «щось корисне».

SKILL.md потрібен не тому, що «так прийнято красиво». Він потрібен, щоб skill перестав жити в голові автора і став відтворюваним артефактом. Ті самі п’ять запитань із минулої лекції — коли викликати, що на вхід, що зробити, що повернути, чого не можна — тепер стають каркасом файла. Відповідаєте хоча б на два з них «ну це й так зрозуміло» — значить, поки не зрозуміло нічого.

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

# Погано
Цей skill допомагає із задачами та робить гарний аналіз.

# Краще
Цей skill перетворює вхідний issue на TASK_SPEC.md
до початку реалізації і не змінює код проєкту.

У другому варіанті вже з’являється головне: призначення і межа. Одразу видно, чого skill не робить. Для issue-analysis це критично: почни він раптом правити код — перестане бути аналітиком і перетвориться на колегу, який прийшов «просто подивитися», а за десять хвилин уже перейменував півпапки.

У контексті нашого курсу це особливо помітно на зв’язці Workflow Kit і Commerce OS. Skill живе в окремому репозиторії Workflow Kit, а застосовується до задач Commerce OS — отже, опис має бути настільки чітким, щоб skill можна було переносити, перевіряти й повторно використовувати. Тут SKILL.md стає не прикрасою, а контрактом.

2. Дві частини SKILL.md

Коли ви відкриваєте SKILL.md, важливо не лякатися обсягу й не намагатися запам’ятати все як таблицю множення. Анатомія проста: верхній блок метаданих (часто оформлюється як frontmatter) і markdown-тіло з інструкціями. Frontmatter — це YAML-блок між трьома дефісами на початку файла, короткий машинночитний опис. Тіло пояснює логіку людською мовою.

flowchart TD
    A[SKILL.md] --> B[Frontmatter
метадані та обмеження]
    A --> C[Тіло
інструкція й контракт результату]
    B --> D[name / description / when_to_use]
    B --> E[allowed_tools / спосіб виклику]
    C --> F[кроки роботи]
    C --> G[що повернути]
    C --> H[чого не робити]

Корисно тримати в голові таку просту таблицю:

Мінімальний каркас виглядає так:

---
name: issue-analysis
description: Перетворює вхідний issue на TASK_SPEC.md
when_to_use: Коли задачу потрібно спочатку проаналізувати, а не одразу реалізовувати
---

## Мета
Підготувати чорновик task spec без змін коду.

Важливо пам’ятати, що точні назви полів залежать від версії Claude Code. Мене цікавить не священний синтаксис, а логіка структури. Розуміння, що skill має метадані й тіло з контрактом, — уже стійкий навик.

На цьому місці виникає природне запитання: гаразд, файл лежить у репозиторії — як він узагалі перетворюється на викликаний workflow? Розділяйте стабільне й мінливе:

Синтаксис може змінюватися, а хороший skill має переживати зміну оболонки. Точний формат звіряйте за поточними /help і документацією.

3. Обов’язкові та опціональні поля

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

Тепер по суті. name — коротке й стійке. Не рекламний слоган. issue-analysis — гарна назва. super-smart-issue-analyzer-for-enterprise-workflows — уже не назва, а симптом того, що автор занадто полюбив своє дітище.

description — це одна коротка фраза про цінність skill. Тут дуже важливо не розтікатися. Порівняйте:

---
name: issue-analysis
description: Допомагає із задачами
when_to_use: Коли потрібно щось проаналізувати
---

І більш робочий варіант:

---
name: issue-analysis
description: Перетворює вхідний issue на TASK_SPEC.md до початку реалізації
when_to_use: Коли є баг, фіча або рефакторинг, і спочатку потрібен план робіт
---

У другому варіанті вже видно, що skill робить і коли його застосовувати. Це особливо важливо для поля when_to_use. «Використовувати під час аналізу» — цінність нульова. Хороший when_to_use описує тригер: ситуацію, після якої вибір skill стає природним. Для issue-analysis це «є вхідний issue, і перед реалізацією потрібен task spec».

Окремо варто сказати про вхідні дані, тобто arguments. Навіть якщо у вашій версії вони оформлюються інакше, ідея одна: skill має явно розуміти, що йому дають на вхід. Текст issue, посилання на пов’язані файли, номер тікета, короткий контекст. Без цього він поводиться як співробітник, якому сказали «розберись», але забули повідомити, в чому саме. Не можете однією фразою описати вхід — skill описано недостатньо чітко.

4. Тіло skill: мета, порядок, результат, заборони

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

Ось короткий, але здоровий фрагмент:

## Мета
Зібрати TASK_SPEC.md за шаблоном проєкту.

## Порядок роботи
1. Прочитайте issue і пов’язані файли.
2. Виділіть scope, non-goals і ризики.
3. Поверніть чорновик без змін коду.

Зверніть увагу на одну важливу річ: тут немає абстрактної філософії на кшталт «думай глибоко і дій професійно» — красиво, але марно. Claude корисніше від конкретного workflow: прочитай issue, знайди пов’язані області, сформулюй scope, поверни конкретний артефакт. Ось це вже інструкція.

Особливо важливий блок очікуваного результату, або, якщо говорити інженерно, контракт результату. Для issue-analysis мало сказати «підготуй аналіз». Назвіть артефакт прямо: TASK_SPEC.md, плюс список відкритих запитань щодо непідтверджених даних. Тоді й людина на перевірці знає, що побачить наприкінці.

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

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

5. Коли запускати і які права давати

Коли контракт уже зібрано, наступне запитання стає операційним: коли запускати skill і якими правами його обмежувати. Думайте не категоріями «зручно / незручно», а категоріями ризику.

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

Для issue-analysis логіка дуже проста: це skill планування, а не реалізації. Отже, йому достатньо читання і пошуку — мінімально потрібні інструменти, без зайвих прав. Skill, який збирає TASK_SPEC.md, не потребує права правити півпроєкту. Це приблизно як дати бібліотекарю відбійний молоток — раптом колись знадобиться, але краще все-таки не треба.

Концептуально верх файла може відображати це так:

---
name: issue-analysis
allowed_tools: read, grep
# запуск лише вручну; точне поле залежить від версії
# редагування файлів не дозволяємо
---

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

6. Збірка issue-analysis для Workflow Kit

Тепер давайте зберемо наш перший нормальний skill не у вакуумі, а в тому самому проєктному контексті, який проходить крізь увесь курс. Мінімальна версія issue-analysis — без зайвих шарів, але з зрозумілим контрактом і безпечними правами. Нагадую важливу архітектурну річ: skill живе не всередині Commerce OS, а в окремому репозиторії Workflow Kit. Це не прискіпування до папок, а інженерна межа: продуктова кодова база і метаінструменти команди — різні артефакти.

Мінімальна структура:

workflow-kit/
  .claude/
    skills/
      issue-analysis/
        SKILL.md
        templates/

Верхня частина файла:

---
name: issue-analysis
description: Перетворює вхідний issue Commerce OS на TASK_SPEC.md
when_to_use: Коли за багом, фічею або рефакторингом спочатку потрібен аналіз, а не реалізація
allowed_tools: read, grep
---

Уже на цьому етапі видно, що skill робить, де застосовується і якими засобами. Далі тіло:

## Що зробити
1. Прочитати issue і пов’язані області проєкту.
2. Виділити мету, scope, non-goals і ризики.
3. Заповнити TASK_SPEC.md за шаблоном.

## Що повернути
Готовий TASK_SPEC.md і список відкритих запитань.

## Чого не робити
Не змінювати код і не починати реалізацію.

Тепер прив’яжімо це до реального прикладу з Commerce OS. Припустімо, надійшов issue: refund-запити в inbox підтримки сортуються в неправильному порядку. Skill не лізе виправляти сортування — він перетворює текст задачі на інженерний артефакт:

## Мета
Виправити порядок refund-запитів в inbox підтримки.

## Область змін
support/inbox, логіка сортування списку, пов’язані тести

## Не-цілі
Не змінювати правила ескалації і не чіпати UI картки тікета.

Ось тут і стає видно, навіщо ми так возилися з анатомією SKILL.md. Добре описаний skill стабільно перетворює сире формулювання на структуру, яку ви вже вмієте читати за модулями про task spec. Він не створює магію, а автоматизує знайому дисципліну.

Саме тому такий skill — хороший перший артефакт Workflow Kit: не лізе в ризиковані зони, не потребує зовнішніх інтеграцій, не роздає широких прав і одразу приносить користь. І його легко перевіряти — відкрили файл, подивилися опис, обмеження, очікуваний результат.

7. Читання чужого SKILL.md

Коли ви відкриваєте чужий skill, ваше завдання — не захопитися красою markdown, а швидко зрозуміти, чи можна йому довіряти. Хороший SKILL.md читається як короткий робочий договір. Прочитали й досі не розумієте, коли його викликати і що він поверне, — красиво, але не інженерно.

Дуже допомагає ось такий набір запитань для перевірки:

Якщо файл відповідає на ці запитання, його вже можна використовувати як командний артефакт. Не відповідає — перед вами не skill, а заготовка. Це нормально, багато перших версій такі. Головне — не вдавати, що заготовка вже зріла.

Для issue-analysis хороший результат читання виглядає так: за хвилину ви розумієте, що skill бере вхідний issue, читає пов’язані області, збирає TASK_SPEC.md, не змінює код і працює з мінімальними правами. Усе. Жодної містики, жодного «автор напевно щось мав на увазі». Коли артефакт не потребує телепатії, він уже придатний для нормального інженерного середовища.