Від skill до plugin: пакування workflow

1. Plugin стоїть у кінці сходів, а не на початку

Дуже хочеться думати, що plugin — це просто «наступний крутий рівень» після skills, і чим раніше ви до нього дістанетеся, тим зрілішими ви будете як інженер. На практиці все навпаки: plugin потрібен пізніше, а не раніше. Він з’являється не тоді, коли ви написали перший хороший workflow, а коли він став достатньо стабільним, щоб передавати його іншим.

В AI-assisted розробці корисно тримати в голові прості сходи зрілості. Спочатку разовий prompt. Потім постійні правила проєкту в CLAUDE.md або rules. Далі повторювану процедуру ви виділяєте в skill. І лише коли процедура переросла особисте використання — думаєте про plugin.

Тут важливо не переплутати ролі. Skill відповідає на запитання «як повторювати процедуру». Plugin — на запитання «як її поширювати, версіонувати й підтримувати». Це різні задачі. Змішаєте — почнете пакувати все, що просто непогано працює локально. Передчасне пакування.

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

Тому сьогодні для нас важлива не думка «plugin крутіший за skill». Важлива інша: plugin потрібен, коли workflow перестав бути особистою зручністю і став командним активом.

2. Всередині одного репозиторію .claude/ ще вистачає

На цьому етапі легко спокуситися думкою: раз навчилися робити SKILL.md — давайте все одразу в plugin. Але .claude/ усередині одного репозиторію часто закриває задачу цілком. Це не костиль, а нормальне рішення, поки workflow живе в межах одного проєкту й однієї команди — або навіть однієї людини.

Уявіть, що ви ведете Commerce OS і написали skill для розбору вхідного issue: він перетворює сирий опис бага на task spec — проблема, scope, non-goals, план перевірки. Така skill спокійно живе прямо в проєкті, поруч з іншими .claude-артефактами.

---
name: issue-analysis
description: Перетворити вхідний issue на структурований task spec.
when_to_use: Перед початком нетривіальної задачі.
---

1. Збери контекст задачі.
2. Виділи scope і non-goals.
3. Сформулюй критерії перевірки.

Якщо цією skill користуєтеся лише ви, якщо вона зав’язана на структуру Commerce OS, якщо ви й досі переписуєте її щодня й ніхто поки не просить «скинь мені це якось по-людськи», то plugin лише додасть роботи. Доведеться думати про версію, README, сумісність, ім’я пакета, namespace і спосіб встановлення. Тобто замість однієї задачі — зробити workflow корисним — ви передчасно берете на себе другу: зробити workflow поставлюваним.

Саме тут новачки часто роблять першу типову помилку. Їм здається, що plugin — ознака зрілості, а .claude/skills/ — щось надто локальне й домашнє. Але інженерна зрілість вимірюється не розміром пакування, а доречністю рішення. Пакувати локальний workflow заради гарного слова plugin — як купувати валізу на колесах, щоб дійти до сусіднього під’їзду.

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

3. Сигнали, що workflow доріс до plugin

Найнебезпечніше тут — промахнутися в часі в обидва боки. Занадто рано винесете в plugin — платите за підтримку марно. Занадто пізно — копіюєте .claude/ між репозиторіями й дивуєтеся, чому в колег різні версії однієї skill. Тому корисно дивитися не на «відчуття крутості», а на конкретні сигнали.

Розберімо це на живому сценарії. Припустімо, ваша issue-analysis спочатку жила лише в Commerce OS. Потім той самий підхід захотіли в CashFlow Dashboard, потім — у третьому репозиторії з внутрішніми інструментами. Поки все маленьке, люди просто копіюють каталог skills/issue-analysis/ з місця в місце. У перший тиждень нормально. До третього один репозиторій уже на новому формулюванні плану перевірки, другий — на старому, а в третьому хтось виправив опис локально й нікому не сказав. Git чесно зберігає зміни — а єдиним артефактом ви вже не керуєте.

Ось у цей момент і з’являється справжній аргумент за plugin. Не «ми стали просунутими», а «нам потрібно доставляти одну процедуру в кілька місць без ручного копіювання». Не смак — узгодженість.

Ще один сильний сигнал — коли ви починаєте дбати про версію. Поки workflow особистий, ви рідко запитуєте: у мене issue-analysis 0.2.1 чи вже 0.3.0? Але щойно ті самі skills використовують інші люди, версія відповідає на дуже практичне запитання: ми про один workflow — чи про схожі, але різні?

Нарешті, є менш очевидна, але дуже життєва ознака. Щойно вам доводиться пояснювати колезі, як саме це встановити, ви вже стоїте на порозі мислення в термінах plugin. Якщо підключити workflow не можна без дзвінка «відкрий ось цю папку, скопіюй сюди, тут підправ руками» — у нього є прихована вартість поширення. Plugin робить її явною й керованою.

4. Plugin — це пакування, а не «скилл із турбонаддувом»

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

Всередині plugin на поточному етапі наших знань лежать ті самі skills, які ви вже вмієте створювати. Пізніше в курсі познайомитеся й з іншими компонентами — їх теж можна пакувати разом. Але зараз головне — не роздувати конструкцію раніше часу: мінімально корисний plugin — це два skills, README і метадані. Цього вже вистачає для командного артефакту.

Нижче — схематичний приклад manifest-файла. Я показую його в YAML, бо так легше читати очима. У вашій версії Claude Code точна назва файла й набір полів можуть відрізнятися, тому тут важливо вхопити не синтаксис, а ідею: у plugin є паспорт.

name: team-review-kit
version: 0.1.0
description: Командний набір для розбору issue та самоперевірки PR.
namespace: review-kit
components:
  - skills/issue-analysis
  - skills/pr-review

Що тут відбувається? Нічого магічного. Ми не посилили issue-analysis — ми просто сказали: ось пакет team-review-kit, ось версія, namespace, компоненти. Розумнішим skill не став, зате в нього з’явився зовнішній контур: його можна обговорювати, встановлювати, оновлювати й підтримувати як єдине ціле. Це мінімальна схема, щоб побачити паспорт пакета; у варіанті для команди майже одразу знадобляться README, changelog і чіткіші межі складу.

Це принциповий зсув мислення. Поки skill живе всередині .claude/, ви насамперед думаєте про зміст: чи гарна інструкція, чи зрозумілий результат, чи не розповзаються межі задачі. З’явився plugin — думаєте про доставку: як називається, як встановлюється, що входить, як не зіткнутися за іменами. Plugin додає не стільки функціональність, скільки операційну оболонку навколо вже корисного workflow.

Тому, коли вам наступного разу захочеться сказати «плагін — це просунутий skill», краще зупиніться й переформулюйте. Skill — одиниця процедури, plugin — одиниця поширення.

5. Три дорослі слова: версія, README і namespace

Поки workflow живе лише у вас, можна дозволити собі затишний хаос. Перейменували skill? Забули записати, як ним користуватися? Змінили поведінку вчора ввечері? Ви й так усе пам’ятаєте. Але перетворили це на plugin — і хаос перестає бути особистим, він множиться через команду. Тоді й з’являються три дорослі слова: версія, README і namespace.

Версія потрібна не для краси — вона фіксує стан артефакту. Навіть 0.1.0 корисна: відповідає, що саме зараз стоїть у колеги. Без неї будь-яке обговорення швидко перетворюється на театр абсурду. Один: «pr-review пропонує додати risk notes», другий: «у мене не пропонує». Хто правий? Обидва. Просто під одним іменем у них різний вміст.

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

# team-review-kit

Пакет для командного review workflow.
Містить skills `issue-analysis` і `pr-review`.
Безпечний профіль: лише skills, без hooks і мережевих дій.
Підходить для репозиторіїв Commerce OS і CashFlow Dashboard.

А тепер namespace. Спочатку це слово здається бюрократичним, але насправді воно рятує дуже земні речі. Уявіть, що одна команда створила skill pr-review, і інша теж створила pr-review. Обидві назви виглядають логічно — світ повен людей, які називають свої артефакти однаково. І тут namespace працює майже як прізвище в людини з поширеним ім’ям. Не просто pr-review, а щось на кшталт review-kit:pr-review. Точний синтаксис префікса може відрізнятися, але сенс завжди один: одразу видно, з якого пакета прийшов цей компонент.

Якщо не продумати namespace заздалегідь, конфлікт приходить не тоді, коли у вас один plugin, а коли їх стає два. І, як зазвичай буває, у найнезручніший день. Тому namespace — не передчасна пересторога, а дешева профілактика.

Зверніть увагу, як змінюється сама природа роботи. Поки ви писали skill, ви відповідали за якість процедури. Тепер ви відповідаєте ще й за зручність підключення, прозорість складу та те, щоб ваш артефакт не ламав чужу ментальну модель. Саме тому plugin не можна вважати просто «наступним полем у конфігу». Це вже маленький продукт усередині команди.

6. Як особиста skill стає team-review-kit

Щоб тема не залишилася абстрактною, прив’яжімо її до нашого наскрізного проєкту. У нас уже є Workflow Kit — репозиторій із повторно використовуваними артефактами для Claude Code. На минулому рівні в ньому з’явився issue-analysis, поруч оформляється pr-review. Поки вони лежать окремо як skills в одному контексті. Але щойно стає зрозуміло, що набором користуватимуться в кількох репозиторіях, з’являється кандидат на пакування. Дивіться на нього як на схематичний мінімальний пакет усередині Workflow Kit, а не як на фінальний знімок артефакта для команди.

workflow-kit/
  plugins/
    team-review-kit/
      plugin.yaml
      README.md
      CHANGELOG.md
      skills/
        issue-analysis/
          SKILL.md
        pr-review/
          SKILL.md

Тут поки що немає нічого зайвого. Перший plugin, готовий для команди, не зобов’язаний бути величезним — навпаки, йому корисно бути маленьким і зрозумілим. Два skills, ясне призначення, охайний README, чесна версія — і інший розробник уже встановить його без шаманства. Пара повторюваних skills перестає бути особистою папкою і збирається у пакет, який можна встановити. Далі артефакт обросте документацією та версіонуванням, але думка видно вже тут.

Уявіть типовий робочий день команди Commerce OS. Приходить issue про неправильне сортування refund-запитів. Інженер запускає issue-analysis, отримує task spec. Після змін — pr-review для швидкого self-review: scope, tests, risk notes, зрозумілість diff. Обидві процедури хочуть у CashFlow Dashboard — і ось вибір: або копіювати два каталоги вручну й жити в режимі «в кого яка версія», або визнати, що це вже командний workflow, і упакувати.

У цій точці важливо не переборщити. Ніякого універсального plugin «для всіх на світі» й внутрішнього marketplace імені себе. Набагато чесніше — невеликий пакет для зрозумілої аудиторії: команди, яка працює з Commerce OS і сусідніми репозиторіями. Артефакт для команди не зобов’язаний бути готовим для всіх. Спершу корисним конкретним людям у конкретній роботі — потім усе інше.

Саме тому хороший перший plugin виглядає досить скромно. Він хороший не кількістю компонентів, а тим, що його можна відкрити й одразу зрозуміти. Навіщо він? Що входить? Яка версія? Де межі? Відповідає колега на це без дзвінка автору — значить, ви справді перейшли від особистого workflow до артефакту, який можна поширювати.

У цьому й полягає справжня зрілість. Не в тому, що ви навчилися писати слово plugin, а в тому, що почали ставитися до свого workflow як до речі, якою користуватимуться інші люди. Щойно в історію входять інші люди, інженерна дисципліна стає дуже практичною: версії перестають бути формальністю, README — прикрасою, namespace — занудством. І plugin перетворюється з модного слова на нормальний спосіб не змушувати команду жити на копіпасті та здогадках.