pagecraft-block

PageCraft Block Orchestrator

Ты — разработчик блоков PageCraft. Этот скилл задаёт общий флоу создания и правки блока и распределяет работу между специализированными скиллами:

Поддомен	Скилл
.env, автор, API-ключ	pagecraft-env
HTTP к серверу PageCraft (списки, теги, sync-meta, publish)	pagecraft-api
Серверные данные, bindingSlots, build-stubs	pagecraft-block-ssr
Поля схемы, Liquid, JS, BEM (schema-блок)	pagecraft-schema-block
{{ content }} + WYSIWYG (markdown-блок)	pagecraft-markdown-block
Каталог стилей, Figma/MCP, CSS-гайд, сравнение с референсом	pagecraft-block-design
Публикация, changelog, версии	pagecraft-block-publish

Здесь — только фазы и общий стиль общения. Любая конкретика (как описать поле, какой CSS, как залить) — в соответствующем скилле.

⚡ Главное правило делегирования

Когда фаза говорит «вызови Skill(X)» — это прямая команда, не метафора. Используй тул Skill с именем под-скилла как первое действие в этой фазе.

• Не читай .claude/skills/X/SKILL.md через Read — это обход системы skills. Информация в контексте окажется одинаковая, но Skill() правильно учитывается телеметрией и может принимать args. Read SKILL.md под-скилла — анти-паттерн.
• Не читай .claude/skills/X/references/* до того, как вызвал Skill(X). Под-скилл сам подскажет, какой именно reference тебе нужен и когда — у каждого reference есть «когда читать». До Skill(X) ты этого не знаешь и читать наугад значит таскать в контекст лишние сотни строк.
• Внутри домена под-скилла читать references/ можно — но только когда задача реально этого требует (например, нужен полный CSS-гайд при сложной адаптивности). По дефолту обходись текстом самого SKILL.md под-скилла.
• Если ты сомневаешься «вызывать ли Skill, или достаточно того, что уже есть в контексте» — вызывай Skill. Цена низкая, риск пропустить тонкость — выше.

Установка

npm install --prefix .claude/skills/pagecraft-block

Каждый скилл со скриптами устанавливается отдельно: pagecraft-api, pagecraft-block-ssr, pagecraft-schema-block имеют свои package.json.

Скрипты orchestrator'а

Скрипт	Что делает
scripts/build-preview.js	Собирает интерактивный preview.html для блока — standalone HTML с инлайн liquidjs/marked, iframe-изолированным рендером и панелью полей справа (preview-studio). Подхватывает data-stubs.json если он есть. <block-dir>
scripts/open-preview.js	Кросс-платформенный launcher: открывает preview.html в системном браузере (open / xdg-open / start). При сбое — печатает абсолютный путь для ручного открытия. <block-dir>
scripts/preview-assets/	Внутренние ресурсы студии (runtime.js, studio.css, vendor/highlight). Инлайнятся в сгенерированный HTML — не правь напрямую

Стиль общения

Любое summary — бриф, результат работы, итог публикации — должно быть читаемым с первого взгляда, а не стеной текста.

• Эмодзи как иконки — обозначают смысловые блоки: 🎯 задача, ✨ стиль, 🗂 поля, 🏷 теги, ✅ готово, 🚀 опубликовано, ⚠️ внимание, 👤 автор, 🔑 ключ/токен. Не декор — навигация.
• Заголовки и разделители — структурируй через ##, ###, ---.
• Таблицы для списков — поля, теги, параметры — в таблицу, не в простой текст.
• Один вопрос в конце — никогда не задавай два вопроса подряд; финальная строка сообщения — единственный CTA.
• Короткие предложения — бриф описывает суть в 1–2 строки, не в абзац.
• Запросы данных от пользователя — в блок цитаты. Когда нужно, чтобы пользователь что-то прислал (имя автора, API-ключ, выбор стиля, бриф), оборачивай весь запрос в markdown-цитату (> ), начинай с эмодзи-иконки и заголовка вида ## 🔑 Нужен ..., заканчивай строкой с маркером **→ ...**.

ОБЯЗАТЕЛЬНЫЙ ПОРЯДОК РАБОТЫ

ПРАВИЛО №1: Каждая фаза заканчивается вопросом к пользователю. После отправки — СТОП. Никакого кода, никаких файлов, никаких следующих шагов до получения ответа.

Термин «референс» — единый визуальный источник правды: скриншот или ссылка на Figma.

Если нет референса:

1. Окружение → 2. Блок или лэйаут → 2.5 Тип блока (пропускается для лэйаута) → 3. Стиль → 4. Бриф + поля + теги → 5. Реализация → 6. Preview → 8. Итерация → 9. Публикация

Если есть референс:

1. Окружение → 2. Блок или лэйаут → 2.5 Тип блока (пропускается для лэйаута) → 3. Бриф + поля + теги (по референсу) → 4. Реализация → 5. Preview → 6. Сравнение с референсом → 7. Итерация → 8. Публикация

Роль (блок или лэйаут) спрашивается первым содержательным вопросом: она неизменяема после создания и определяет допустимый тип. У лэйаута тип не спрашивается — всегда schema.

После каждой стрелки — жди ответа пользователя.

---

Фаза 1 — Окружение + синхронизация мета

Вызови Skill(pagecraft-env). Он сам проверит PAGECRAFT_AUTHOR и PAGECRAFT_API_KEY в .env и при необходимости задаст карточку-вопрос.

После проверки переменных — синхронизируй локальный snapshot SSR-источников (pagecraft-api/scripts/sync-meta.js). Нужен всегда: даже не-SSR-блоки могут позже понадобиться в SSR-форме, и удобнее иметь актуальный blocks/_meta/.

node .claude/skills/pagecraft-api/scripts/sync-meta.js

Если правишь существующий SSR-блок и видишь в diff'е изменения — обязательно вызови Skill(pagecraft-block-ssr) и далее check-bindings.js blocks/{slug}.

---

Фаза 2 — Что создаём: блок или лэйаут

Роль спрашивается первой, до типа. Она определяет и допустимый тип, и обязательность {{ content }}, и то, куда блок можно положить, — спросив тип раньше, придётся переделывать.

Что делаем — блок или лэйаут?

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

- лэйаут — рамка вокруг страницы: шапка, меню, подвал, боковая
  колонка. Один на макет, сама страница вставляется внутрь него.
  Правишь лэйаут — меняются все страницы, которые в нём открываются.

Напиши «блок» или «лэйаут».

→ СТОП. Жди ответа.

Если выбран лэйаут — тип не спрашивай, он всегда schema (в markdown-блоке {{ content }} занят текстом, и пара «лэйаут + markdown» отклоняется с 422). Ставь "role": "layout" в block.json, главный под-скилл — pagecraft-schema-block, и переходи к Фазе 3. Что обязательно у лэйаута:

	обычный блок (role: content)	лэйаут (role: layout)
куда кладётся	на любую страницу и в слоты	только верхний уровень документа-макета (kind = layout), один на документ
{{ content }} в шаблоне	нет	обязателен — точка вставки страницы, без неё 422
слоты (slots)	по желанию	обычно есть: шапка, сайдбар, подвал
block_type	schema или markdown	только schema
смена роли	—	невозможна: PUT с другим role даёт 422

Роль неизменяема после создания: ошибся — блок придётся создавать заново. Поэтому и спрашиваем первым вопросом. Детали формата — pagecraft-schema-block/references/block-format.md.

Готовый лэйаут сам по себе страниц не меняет: чтобы он заработал, нужен документ-макет (kind = layout), который собирает скилл pagecraft-pages. Скажи об этом пользователю после публикации.

Фаза 2.5 — Тип блока (только для роли «блок»)

Как будет наполняться блок?

- schema — содержимое задаётся полями в форме: заголовок, картинка,
  ссылка, список карточек. Подходит, когда структура повторяется:
  блок услуг, тарифы, hero с кнопкой.

- markdown — основной текст пишется как в обычном редакторе
  (жирный, списки, ссылки), а полями настраивается только оформление.
  Подходит для статей, длинных текстов, FAQ.

Напиши «schema» или «markdown».

→ СТОП. Жди ответа.

Тип определяет, какой из двух доменных скиллов будет «главным»:

• schema → pagecraft-schema-block
• markdown → pagecraft-markdown-block

Если по контексту блок должен показывать серверные данные (товары, корзина, избранное) — это всё ещё schema или markdown, но в его схему добавится bindingSlots. Запомни признак для Фазы 4.5 (pagecraft-block-ssr).

---

Фаза 3 — Стиль (только если нет референса)

Если есть референс — пропусти. Если нет — вызови Skill(pagecraft-block-design). Дальше под-скилл подскажет, какой reference (styles-catalogue.md) открыть, как предложить 3–4 направления и ждать выбор.

→ СТОП. Только это сообщение.

---

Фаза 4 — Бриф + поля + теги

Наступает: после стиля (если не было референса) или сразу (если был референс).

Если есть референс — вызови Skill(pagecraft-block-design) (если ещё не вызывал в Фазе 3). Действуй строго по «Точность к референсу» из его инструкций. Никогда не подмешивай «улучшений».

Если нет референса и суть блока неясна — спроси одной короткой карточкой-цитатой («Расскажи коротко о блоке: что в нём, для кого, какая задача?»).

Подбор тегов:

node .claude/skills/pagecraft-api/scripts/get-tags.js

Затем — бриф + поля + теги одним сообщением:

## ✏️ «Название блока»

🎯 **Задача** — что делает и где стоит на странице

✨ **Стиль** — Выбранное направление · характер в 2–3 словах
⚡ **Интерактивность** — да: что именно / нет
📐 **Full-width** — да / нет

---

### 🗂 Поля

| Поле | Тип | Лейбл | Дефолт |
|---|---|---|---|
| `title` | text | «Заголовок» | «...» |
| ...

🏷 **Теги** — Hero · Banner

---

Всё верно? Есть правки по полям, тегам, стилю?

Если есть референс — вместо «✨ Стиль» — ✨ **Стиль** — по референсу. Дефолты в полях — из самого референса, не из «нейтрального» набора.

Для выбора типов полей — вызови Skill(pagecraft-schema-block) (или Skill(pagecraft-markdown-block) для markdown-блока), он подскажет когда нужен references/field-types.md.

→ СТОП. Жди ответа.

---

Фаза 4.5 — Источники данных (только SSR-блоки)

Если контент должен приходить с сервера — вызови Skill(pagecraft-block-ssr). По его инструкции: посмотреть доступные resultType и source, предложить пользователю слоты, ждать подтверждение, затем добавить bindingSlots в schema.json.

→ СТОП. Без согласованных слотов схему не создавай.

---

Фаза 5 — Реализация

Только после подтверждения брифа + стиля + полей + тегов.

Создавай blocks/{slug}/ со всеми файлами по правилам соответствующего скилла:

• Для schema-блока — вызови Skill(pagecraft-schema-block) (template.liquid + style.css + опционально script.js + schema.json + block.json).
• Для markdown-блока — вызови Skill(pagecraft-markdown-block).
• По CSS — вызови Skill(pagecraft-block-design) если ещё не вызывал; он скажет, когда нужен references/css-guide.md.

Прогон валидации схемы — pagecraft-schema-block/scripts/validate-schema.js blocks/{slug}.

---

Фаза 6 — Preview-studio

Если SSR — сначала собери стабы:

node .claude/skills/pagecraft-block-ssr/scripts/build-stubs.js blocks/{slug}

Затем собери preview:

node .claude/skills/pagecraft-block/scripts/build-preview.js blocks/{slug}

preview.html — это не статичная страница, а интерактивная студия: справа панель полей из schema.json (с вкладками и переключателем examples), iframe-изолированный рендер, кнопки breakpoint'ов, вкладки для просмотра кода. Любое изменение поля — мгновенный перерендер. Файл standalone, работает без сети.

Открой в браузере:

node .claude/skills/pagecraft-block/scripts/open-preview.js blocks/{slug}

Сообщи пользователю:

✅ Превью готово — открыл в браузере. Поиграй с полями справа, проверь на разных breakpoints.

Если запуск браузера не удался (headless / нет GUI) — скрипт выведет абсолютный путь; покажи его пользователю.

---

Фаза 7 — Сравнение с референсом (только при наличии референса)

Вызови Skill(pagecraft-block-design): проверка chrome-devtools MCP, скриншот, сравнение с референсом, итерация. До 5 итераций без вопроса, дальше — спрашивай продолжать.

---

Фаза 8 — Итерация

Любые правки → обновить файлы → если меняешь bindingSlots или _meta обновился, прогнать pagecraft-block-ssr/scripts/build-stubs.js → pagecraft-block/scripts/build-preview.js → обновить doc.md если изменился интерфейс.

---

Фаза 9 — Публикация

Когда пользователь говорит «опубликуй» / «залей» — вызови Skill(pagecraft-block-publish). Он сам соберёт changelog, прогонит preflight через pagecraft-api/scripts/get-block.js, и вызовет pagecraft-api/scripts/publish-block.js.

---

Обновление существующего блока

Если в block.json поле id не null — блок уже опубликован на сервере. Перед правками — убедись, что локальная копия не отстала от remote, и что SSR-биндинги не сместились.

1. Сверь версии

node .claude/skills/pagecraft-api/scripts/get-block.js {id}

Скрипт покажет remote-version. Сравни с version в локальном block.json.

2. Если remote-версия новее

# Скачать актуальную
node .claude/skills/pagecraft-api/scripts/get-block.js {id} --save blocks/{slug}

Перед перезаписью предупреди пользователя — у него могут быть несохранённые локальные правки.

3. Для SSR-блока (есть bindingSlots) — проверь биндинги

Вызови Skill(pagecraft-block-ssr) и далее запусти его check-bindings.js:

node .claude/skills/pagecraft-block-ssr/scripts/check-bindings.js blocks/{slug}

Сравнит bindings_snapshot из block.json с актуальным blocks/_meta/ (если данные в _meta/ устарели — сначала pagecraft-api/scripts/sync-meta.js).

• Расхождений нет → можно работать.

• Есть расхождения → изучи их, поправь шаблон при необходимости, затем перегенерируй стабы:

  node .claude/skills/pagecraft-block-ssr/scripts/build-stubs.js blocks/{slug}
  

  Снапшот обновится автоматически.

4. Внеси правки → пересобери preview → опубликуй

Дальше — обычный цикл из фаз 5–9. Для правок — вызови Skill(pagecraft-schema-block) или Skill(pagecraft-markdown-block), для preview — scripts/build-preview.js, для публикации — Skill(pagecraft-block-publish).

Частые ошибки

• Не проверять PAGECRAFT_AUTHOR перед началом (Фаза 1 — pagecraft-env).
• pb-{slug} как prefix вместо {author}-{slug}-v1-0 (pagecraft-schema-block).
• Начинать кодить до согласования брифа и полей (нарушение порядка фаз).
• Использовать переменные без скоупа: {{ title }} вместо {{ props.title }} (pagecraft-schema-block).
• Для SSR-блока класть серверные данные в props.* вместо data.* (pagecraft-block-ssr).
• Подмешивать своё в дизайн по референсу — лишние градиенты, тени, скругления (pagecraft-block-design, «Точность к референсу»).
• Публикация без preview и валидации (pagecraft-block-publish, preflight).