Користувацький плагін: прототип, готовий для команди

1. Момент, коли папка стає пакетом

Щойно ви перестаєте вибирати чужий пакет і починаєте збирати свій, правила не стають мʼякшими — планка не опускається ані на сантиметр.

Ми вже відокремили skill від plugin. Тримайте камертон: skill — одна повторювана процедура, plugin — пакет, який робить набір таких процедур переносним і зрозумілим іншим. Питання сьогодні інше: що має зʼявитися в момент, коли ваш workflow виходить з особистої папки й стає командним артефактом?

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

Для Workflow Kit це важливо подвійно: ми не пришиваємо фічу всередину Commerce OS, а збираємо інженерний набір для підключення до проєктів. Отже, пакету потрібні паспорт, читабельна структура й мінімальний склад, який можна перевірити на око.

2. З чого зібраний мінімальний team-ready plugin

Зараз дуже легко перестаратися. Щойно ви чуєте слово «архітектура», мозок одразу малює багатоповерхові схеми, пʼять шарів абстракції та загадкову папку core. Не треба. Мінімальний plugin — невеликий читабельний пакет: skills, метадані, документація, приклади й чесна історія змін. Ось його каркас.

Нижче — зручна таблиця, на яку можна спиратися як на каркас першого прототипа.

plugin metadata

skills/

README.md

examples/

CHANGELOG.md

compatibility notes

install instructions

Зверніть увагу на одну важливу деталь. Тут немає agents, немає hooks, немає MCP, немає shell-скриптів. Не тому, що все це погано. Просто сьогодні ми збираємо мінімальний пакет, готовий для команди, на тому наборі знань, який вже добре розуміємо й можемо перевірити на око. Майже завжди це найкращий старт. Перший plugin має допомагати команді, а не справляти враження на сусідній відділ.

Нижче — внутрішня структура самого пакета. Він може жити всередині репозиторію Workflow Kit, але тут важливий саме склад плагіна, а не його зовнішній шлях у дереві репозиторію.

Типова структура такого пакета може виглядати ось так:

team-review-kit/
├── plugin.json
├── README.md
├── CHANGELOG.md
├── skills/
│   ├── issue-analysis/
│   │   └── SKILL.md
│   ├── pr-review/
│   │   └── SKILL.md
│   └── project-setup/
│       └── SKILL.md
└── examples/
    ├── issue-analysis-example.md
    └── pr-review-example.md

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

3. Збираємо team-review-kit із трьох знайомих skills

Тепер давайте зберемо наш мінімальний прототип із того, що вже логічно виросло з курсу: issue-analysis, pr-review і невеликий helper project-setup. Компактний пакет на ділянку «від вхідного issue до охайної підготовки PR» — за таке команда подякує.

Почнемо з manifest-файла. Точна назва й набір полів залежать від версії Claude Code, тож нижче — умовний приклад: дивіться на нього як на орієнтир, а не як на священну табличку, висічену в граніті назавжди.

{
  "name": "team-review-kit",
  "version": "0.1.0",
  "description": "Командний набір skills для аналізу issue і підготовки PR.",
  "namespace": "review-kit",
  "components": [
    "skills/issue-analysis",
    "skills/pr-review",
    "skills/project-setup"
  ]
}

Що тут важливо? Два поля вирішують багато. Імʼя: plugin-tools не говорить нічого, team-review-kit одразу відсилає до командного review workflow. Namespace: він потрібен не для краси, а щоб ваші skills не зіткнулися за назвами з чужими — дешева страховка навіть у межах одного plugin.

Тепер подивімося на один із вхідних skills — наприклад, pr-review. Від того, що ви поклали його в plugin, SKILL.md не змінює природи: той самий skill з призначенням, обмеженнями й результатом. Але тепер він живе всередині набору, який можна поширювати — отже, опис має бути особливо ясним.

---
name: pr-review
description: Перевіряє diff перед PR і повертає ризики з доказами.
when_to_use: Коли зміни вже зроблені й потрібен локальний self-review.
allowed_tools: read-only
---

Поверни список ризиків, спірних місць у diff, відсутніх перевірок
і короткий підсумок, який можна використати в описі PR.

Якщо придивитися, тут немає нічого надзвичайного — і це чудовий знак. Добрий plugin не вигадує нову фізику, а збирає робочі шматки в пакет, який легко встановити й підтримувати. Так само додаються issue-analysis — перетворювати сире issue на структурований task spec, і project-setup — перевіряти базовий стан Git, наявність CLAUDE.md та домовленостей проєкту перед стартом. Набір логічно замкнений: не випадкові skills з трьох світів, а одна ділянка — прийняти задачу, підготувати проєкт, перевірити зміни перед PR.

4. Версія, сумісність і CHANGELOG.md

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

Для першої версії не треба вдавати з себе великого постачальника платформних рішень і одразу писати 1.0.0. Молодий, але реальний прототип чесніше почати з 0.1.0 — номер прямо каже: ставити вже можна, але пакет ще росте. Здорова інженерна скромність, а не слабкість.

Дуже допомагає й простий CHANGELOG.md — не хроніка з часів динозаврів, а короткий запис, що зʼявилося у версії.

## 0.1.0

- упаковано skills issue-analysis, pr-review і project-setup
- додано приклади використання
- зафіксовано namespace і базову сумісність

А нотатки про сумісність краще писати чесно й спокійно. Перевіряли лише на поточному наборі команд і менеджері plugins у вашому середовищі — так і напишіть; чесна документація корисніша за пафосну обіцянку. Можна завести й маленьку таблицю.

0.1.0

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

5. README — частина архітектури, а не салатик зверху

Дуже хочеться ставитися до README.md як до ввічливого додатка до справжнього артефакту: plugin серйозно, а README так, декоративний салатик зверху. Насправді навпаки. Без README ваш plugin не готовий для команди навіть з чудовими skills всередині: для колеги plugin починається не з JSON і не з папки skills/, а з відповіді на три запитання — що це, як установити і чим воно мені загрожує.

Добрий README не має бути величезним — але зобовʼязаний знімати стартову невизначеність. Фрагмент для першої версії:

# team-review-kit

Набір skills для командного workflow: аналіз issue, перевірка проєкту
перед початком роботи й локальний review diff перед PR.

## Що входить
review-kit:issue-analysis
review-kit:pr-review
review-kit:project-setup

## Безпека
У цій версії немає hooks, agents, MCP і shell-скриптів.
Пакет обмежений skills і розрахований на user або project scope.

Зверніть увагу, тут вже є все основне. Людина бачить, що пакет робить, з чого складається і якою є його capability surface — не лише «що корисного вміє», а й «наскільки далеко може залізти». Немає hooks, agents, зовнішніх підключень і скриптів — добра новина, напишіть її прямо.

У README ще корисно додати короткий блок про встановлення. Але точні команди й навіть назва менеджера plugins змінюються — пишіть практично: «встановлюється через поточний менеджер plugins у user або project scope; після встановлення доступні такі-то namespaced skills». Без хибної вічності.

Є простий тест на якість: не може колега встановити й використовувати plugin без особистого повідомлення вам у месенджері — README ще не готовий. Не катастрофа — привід дописати два абзаци й один приклад.

6. Що ви свідомо НЕ кладете в перший прототип

Коли ви вперше збираєте plugin, особливо після кількох лекцій про розширюваність, дуже важко втриматися й не покласти туди «ще трішки корисного». Потім ще. І ще. А в прототипі раптово вже hook, напівготовий агент, підключення до зовнішнього сервісу та скрипт, який автор «потім обовʼязково почистить». Спойлер: не почистить. Зрілість тут не в кількості компонентів, а в умінні зупинитися.

Для наочності зручно порівняти здоровий стартовий прототип і варіант, у якому перестаралися.

Чому ми не кладемо в першу версію agents, hooks і зовнішні інструменти? Вони розширюють поверхню ризику і потребують окремої розмови про права, події, ізоляцію контексту та життєвий цикл. Увімкніть їх раніше, ніж команда готова, — і акуратний пакет стане тривожним. А тривожний plugin усі ставлять один раз, а потім тихо оминають.

І ще одна тонка річ: готовий для команди не означає готовий для всіх. Перший пакет не зобовʼязаний розвʼязувати проблеми всіх команд, усіх репозиторіїв і заодно людства. Добрий старт — вузький і зрозумілий пакет під один workflow; у нас це review і підготовка issue-to-PR.

7. Секунда, в яку plugin стає командним

Найчесніший тест будь-якого прототипа — не те, як гарно він виглядає в автора, а що трапляється при зустрічі з іншим розробником. Не з тим, хто сидів поруч і чув усі пояснення, — з колегою, який відкрив репозиторій, побачив пакет і спробував ним скористатися. Тут і зʼясовується: був у вас plugin чи просто добре організована особиста папка.

Уявіть такий сценарій. Інший розробник відкриває Workflow Kit, бачить team-review-kit, читає README і за кілька хвилин розуміє три речі: пакет аналізує issue, перевіряє базовий стан проєкту й робить локальний review diff; у першій версії він безпечний і обмежений skills; у нього зрозуміла версія та коротка історія змін. Далі встановлює plugin у відповідний scope, викликає namespaced skill, отримує результат — і не питає вас, що означає половина файлів. У цю секунду plugin перестає бути вашою особистою магією і стає командним інструментом.

Але до розгортання на команду він усе одно проходить той самий дорослий фільтр, що й зовнішній кандидат: зрозумілий власник, зрозуміла capability surface, README, версія, шлях вимкнення й усвідомлений вибір scope — про це ми говорили в минулих лекціях. Те, що ви зібрали plugin самі, не робить його автоматично безпечним чи придатним для project scope.

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

1

Опитування

Від skill до plugin, рівень 10, лекція 4

Недоступний

Від skill до plugin

Від skill до plugin

Відкрити