От 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 и self-review 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 превращается из модного слова в нормальный способ не заставлять команду жить на копипасте и догадках.