Custom plugin: team-ready prototype

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 и возвращает риски с evidence.
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 и рассчитан на project/user 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

Задача

Claude code, 10 уровень, 4 лекция

Недоступна

Создать минимальный plugin manifest

Создать минимальный plugin manifest

Открыть

1

Опрос

От skill к plugin, 10 уровень, 4 лекция

Недоступен

От skill к plugin

От skill к plugin

Открыть