Внутри finestructure-ai/claude-plugin: плагин Claude Code из семи файлов

Весь репозиторий это семь файлов

Склонируйте его, и дерево файлов уместится на одном экране:

.claude-plugin/
  plugin.json        686 B
  marketplace.json   507 B
commands/
  deploy.md          3.3 KB
  fs-domain.md       905 B
  fs-status.md       741 B
skills/
  fine-structure/
    SKILL.md         4.0 KB
LICENSE              MIT
README.md            2.3 KB

Ни package.json, ни файла блокировок, ни CI, ни dist. Ничего не компилируется и не собирается в бандл, и не существует такой версии этого репозитория, сборка которой могла бы упасть. Если вы откладывали написание плагина, потому что предполагали наличие тулчейна, вот поправка: формат это соглашение о структуре каталогов плюс два файла JSON, а всё остальное проза.

Файл plugin.json это указатель, а не программа

Манифест несёт обычные поля идентификации (name, версия 0.1.0, description, author, homepage, repository, license, keywords), а затем один блок, который и делает всю интересную работу:

"mcpServers": {
  "finestructure": {
    "type": "http",
    "url": "https://finestructure.ai/api/mcp"
  }
}

Два ключа. Ни command, ни args, ни env. Сравните это с формой, которую принимает большинство конфигураций MCP: локальный процесс (npx, uvx, путь к бинарнику), список аргументов и карта env с ключом API. Объявление конечной точки streamable HTTP вместо этого выносит сервер за пределы машины пользователя, и именно поэтому 105 инструментов (число, которое приводит файл skill) стоят за манифестом в 686 байт. Ничто в версии Node или Python у пользователя не способно сломать установку, а изменения на стороне сервера доезжают без выпуска новой версии плагина. Плата за это воспроизводимость: зафиксировать набор инструментов со стороны клиента вы не сможете.

Файл marketplace.json превращает репозиторий в собственный канал распространения

Claude Code ставит плагины из маркетплейсов, а не из реестра пакетов, а маркетплейс это файл JSON, который перечисляет плагины с указанием пути к источнику. Второй файл в каталоге .claude-plugin делает именно это, и в его единственной записи плагина стоит "source": "./". Репозиторий одновременно и сам плагин, и раздающий его маркетплейс, так что публикация сводится к публичному git push:

/plugin marketplace add finestructure-ai/claude-plugin
/plugin install finestructure@finestructure

Два одинаковых токена во второй строке это имя плагина при имени маркетплейса, и совпали они потому, что оба называются finestructure. Если копируете такую схему, назовите их по-разному. Инструкция по установке станет понятнее, и у вас останется место, чтобы позже добавить второй плагин.

Команды это шаблоны промптов с frontmatter

Каждый файл в commands/ это frontmatter в формате YAML плюс проза. Файл deploy.md объявляет description и argument-hint, две строки, которые пользователь видит в списке выбора, а затем раскладывает нумерованное дерево решений: проверить корень проекта на наличие .finestructure.json с app_id, иначе вызвать list_apps и поискать совпадение по имени, иначе считать это первым развёртыванием и взять $ARGUMENTS как имя приложения. Файл fs-status.md весит 741 байт и делает работу подкоманды CLI: определить приложение, вызвать get_app_status, get_app_links и get_errors, подвести итог. Файл fs-domain.md по порядку проходит add_custom_domain, get_domain_verification, check_domain_verification, get_domain_ssl_status и set_primary_domain.

Суть замысла в том, что ни один из этих файлов ничего не вызывает. Они называют инструменты, задают порядок и описывают, что делать, когда шаг не удался. Исполнение происходит тогда, когда модель вызывает инструменты MCP. Слэш-команда это промпт, положенный в систему контроля версий, поэтому её ревью сводится к вопросу не о том, верна ли логика, а о том, не двусмысленна ли инструкция.

Лучшие строки здесь запрещающие. Файл deploy.md запрещает инструменты удаления, если пользователь не попросил об этом явно. Файл fs-domain.md отмечает, что распространение DNS занимает от минут до часов, и велит предложить повторить попытку позже, а не крутиться в цикле проверки. Это политика повторных попыток и защитные ограждения, записанные обычными предложениями, и именно этого не хватает наивным плагинам.

skill против command: вытягивание против проталкивания

В файле skills/fine-structure/SKILL.md два поля frontmatter, name и description, причём description читается как условие срабатывания, а не как краткое изложение: использовать всякий раз, когда пользователь хочет развернуть, создать или обновить приложение, подключить домен, поработать с данными или секретами. Такая формулировка выбрана намеренно. Команда срабатывает потому, что человек её набрал. Skill срабатывает потому, что модель сопоставила описание с происходящим.

Отсюда следует и разделение содержимого. Файл SKILL.md это ментальная модель, а не список задач: что здесь считается приложением (страницы JSX, общие компоненты, схемы сущностей, никакого произвольного серверного кода), что такое сущности, какие операции тратят кредиты. Дальше рабочие процессы в виде цепочек инструментов: get_app_files, затем read_app_file, затем write_app_file, затем validate_app, затем publish_app, с наборами изменений для правок в нескольких файлах. Дальше семантика ошибок, у которой самый большой вес на байт: ошибки авторизации означают переподключение, ошибки кредитов означают пополнение, и повторять бессмысленно ни те, ни другие. Агент без этого знания будет в цикле повторять непоправимый сбой, а на платформе со счётчиком у такого цикла есть цена.

Правило для вашего собственного плагина выводится отсюда чисто. Если файл команды объясняет, что такое ваш продукт, этому абзацу место в skill. Команды остаются процедурами.

OAuth это причина, по которой в манифесте нет секретов

Конечная точка аутентифицируется по OAuth 2.1 с динамической регистрацией клиента, поэтому первый же вызов инструмента открывает в браузере страницу согласия, а токен оседает в хранилище учётных данных Claude Code, а не в репозитории. Форк безопасен по построению, отзыв доступа выполняется на стороне сервера, а не правкой конфигурации, которая должна дойти до каждой машины, и никого не просят вставить долгоживущий ключ в файл, до публичного diff которому остаётся один неосторожный коммит.

Что скопировать в свой плагин

Конкретные ориентиры, примерно в порядке сборки:

• Начните с .claude-plugin/plugin.json, где есть name, version и description. Всё остальное необязательно.
• Если у вас есть размещённая конечная точка MCP, объявляйте "type": "http" с url вместо локальной команды. Это убирает среду выполнения пользователя из зоны вашей поддержки.
• Пока плагин один, кладите marketplace.json в тот же репозиторий с "source": "./" и дайте ему имя, отличное от имени плагина.
• Дайте каждой команде description и argument-hint во frontmatter, написанные как ответы на вопросы, что она делает и что набирать после неё.
• Используйте $ARGUMENTS вместо изобретения позиционного синтаксиса. Парсера здесь нет, есть только подстановка.
• Пишите тело команды как дерево решений с явно названными инструментами. Фраза "если файл конфигурации есть, прочитай app_id, иначе вызови list_apps" держится лучше, чем абзац о намерениях.
• Запишите семантику отказов: какие ошибки окончательные, какие можно повторить, что сказать вместо повтора.
• Назовите свои разрушительные инструменты прямо в тексте и запретите их, пока о них не попросили.
• Держите модель предметной области в SKILL.md, а процедуру в команде. Дублирование между ними дурной знак.
• Проверьте через /plugin marketplace add на локальном пути или на своём форке, прежде чем отправлять кого-то на main.

Шероховатости

Три честных, и ни одна не смертельна. Всё написано по-английски, и формат не предлагает никакой зацепки, чтобы это исправить: ключа locale во frontmatter нет, так что локализация означает либо дублирование файлов команд, либо согласие на несоответствие.

У истории про отсутствие ключей API есть звёздочка. Файл SKILL.md признаёт, что инструменты генерации медиа находятся вне соединения OAuth и требуют статического токена MCP с медийными правами, который создаётся в Studio платформы и отправляется заголовком bearer. Плагин справляется с этим хорошо, велит модели объяснить нехватку, а не биться в стену повторами, но это второй путь аутентификации, прикрученный к дизайну, чьё главное достоинство в том, что путь всего один.

И это версия 0.1.0 без changelog, тестов и CI. Для markdown такое простительно, хотя проверка схемы JSON в pre-commit hook ловила бы единственный класс ошибок, который действительно ломает установку, то есть испорченный манифест. Заявка в каталог на момент написания находится на рассмотрении, так что пока установка идёт по ссылке на репозиторий.

Читайте сначала три файла команд, потом SKILL.md, потом два файла JSON. В таком порядке формат объясняет сам себя: markdown решает, что должно произойти и в каком порядке, сервер MCP решает, что выполняется на самом деле, а манифест это тонкий шов между ними.