app-builder · microsoft — скилл для Claude Code: приложения Power Apps из текста
Скилл app-builder собирает и правит model-driven приложение Power Apps по описанию словами: спека в JSON, согласование плана, затем сборка движком cds-maker-sdk.
MIT ★ 1 167 обновлён 2026-10-29
/plugin marketplace add microsoft/power-platform-skills
/plugin install model-apps@power-platform-skillsЧто делает app-builder
Скилл превращает описание приложения словами в развёрнутое model-driven приложение Power Apps. Сначала он вместе с вами собирает App Spec в JSON: таблицы, колонки, связи, формы с sub-grid, представления, графики по колонкам Choice, бизнес-правила, бизнес-процессы, генеративные страницы для обзоров и дашбордов, модуль приложения и карту сайта. План показывается на подтверждение — сборка начинается после согласования.
Дальше по спеке собирает детерминированный движок cds-maker-sdk; повторный запуск идемпотентен. Развёрнутое приложение можно скачать обратно в спеку, поправить и пересобрать. Правки команд и веб-ресурсов при пересборке не переразворачиваются, поэтому кнопку или скрипт сначала удаляют.
Область узкая: canvas-приложения, Power Pages, Power Automate и обычный сайт на React скилл не делает. На лёгкой модели он сам предложит переключиться на общую кодовую или продвинутую reasoning-модель, потому что проектирование зависимостей между таблицами и сверка с тем, что уже есть, требуют многошагового планирования.
Какие задачи решает
- собрать приложение учёта заявок из описания словами
- добавить бизнес-процесс согласования в существующее приложение
- скачать развёрнутое приложение обратно в спеку и поправить формы
- настроить бизнес-правила на форме без JavaScript
- вывести график по колонке Choice в представлении
Примеры запросов агенту
/app-builderсобери приложение для учёта заявок на ремонт оборудования/app-builderдобавь в приложение бизнес-процесс согласования договора/app-builderскачай развёрнутое приложение в спеку и добавь поле «Приоритет»
Как установить app-builder
1Через маркетплейс плагинов
/plugin marketplace add microsoft/power-platform-skills/plugin install model-apps@power-platform-skillsКоманда ставит плагин model-apps целиком, со всеми его скиллами
2Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill app-builder -a claude-code3Вручную: положить файлы
~/.claude/skills/app-builder/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/app-builder/
1Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill app-builder -a codex2Вручную: положить файлы
.agents/skills/app-builder/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill app-builder -a cursor2Вручную: положить файлы
.cursor/skills/app-builder/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install microsoft/power-platform-skills plugins/model-apps/skills/app-builder2Вручную: положить файлы
.github/skills/app-builder/SKILL.md1Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill app-builder -a gemini-cli2Командой платформы
gemini skills install https://github.com/microsoft/power-platform-skills --path plugins/model-apps/skills/app-builderВручную: положить файлы
.devin/skills/app-builder/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об app-builder
Как установить app-builder в Claude Code?
Добавьте маркетплейс командой /plugin marketplace add microsoft/power-platform-skills, затем поставьте плагин: /plugin install model-apps@power-platform-skills.
Что делает app-builder?
Собирает App Spec в JSON по вашему описанию и после подтверждения плана разворачивает model-driven приложение Power Apps через cds-maker-sdk. Уже развёрнутое приложение умеет скачивать обратно в спеку для правок.
Чем app-builder отличается от /genpage?
/app-builder строит приложение целиком и в /genpage не нуждается. /genpage берут, когда нужна отдельная генеративная страница для приложения, которое уже существует.
Исходный текст
SKILL.md · MIT
---
name: app-builder
version: 1.0.0
description: Builds and edits a model-driven Power Apps app from a natural-language intent — tables, columns, relationships, adaptive forms with sub-grids, views, Choice-column charts, business rules, business process flows, generative page intents for overview/dashboard surfaces, and an app module + sitemap. Runs an interactive authoring flow with plan approval and can download a deployed app back into an editable spec to change it. Use when the user says "build an app for X", "create a model-driven app", "make me an app to manage Y", "add a business process flow", or "edit/add to my app". Do not use it for a generic web or React app or website, Power Pages, canvas apps, or Power Automate, or when the user rules out Power Platform, Dataverse, or model-driven apps (for example "no Power Platform"). This skill stands alone and does not require /genpage — but for a standalone generative page added to an app that already exists, use /genpage instead.
author: Microsoft Corporation
argument-hint: "<app description>"
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion, EnterPlanMode, ExitPlanMode, TaskCreate, TaskUpdate, TaskList, read, edit, execute, search, agent, todo
---
> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.
> **Model check (lightweight models only)**: If you are a lightweight model optimized for fast, simple tasks, tell the user in your first message that `/app-builder` works best on a general-purpose coding model or an advanced reasoning model — designing the App Spec, reasoning about the dependencies between tables, relationships and artifacts, orchestrating the build and reconciling what already exists take multistep planning, tool use and validation — and recommend switching; then continue. On any other model, skip this note and say nothing about it.
# app-builder — intent → model-driven app
Turn a natural-language intent into a deployed model-driven app. You author a reviewable **App Spec**
(JSON) with the user across confirmed turns, then a deterministic engine (`cds-maker-sdk`, vendored)
builds it — tables/columns/relationships, sample data, views, Choice-column charts, adaptive forms
with sub-grids, **generative pages** for overview/dashboard surfaces, and the app module + sitemap.
The **same spec drives create and edit**: download a deployed app back into a spec, change it, and
re-run the build (it's idempotent).
## CRITICAL — run the interactive flow in THIS conversation (the main loop)
> **You MUST run the authoring questions and the build narration yourself, in the main
> conversation. Do NOT dispatch a subagent (`Task`) for the interactive steps.**
>
> A subagent is headless — `AskUserQuestion` and plan mode do not reach the user from inside one
> (its only output is its final message). The whole point of this skill is the multi-turn,
> propose-then-confirm experience, so every `AskUserQuestion`, `EnterPlanMode`, and live build
> status line must originate here, in the main loop.
## CRITICAL — the user sees your chat message, NOT tool output
> **Shell/tool output — the result of running `preview-app.js`, a dry-run plan, or a lint —
> is COLLAPSED BY DEFAULT in the UI. The user does NOT see it unless they manually expand the
> tool panel.** Running the command is therefore NOT the same as showing the user. Every artifact
> the user must **read, review, or approve** — the whole-app **preview wireframes**, the
> **dry-run build plan**, and blocking **lint findings** — MUST be reproduced **verbatim in your
> chat reply**, inside a fenced ` ``` ` code block. Never say "the preview looks right" and leave
> the content buried in a collapsed panel: **paste it into your message.** This is the #1 cause of
> "the wireframes aren't visible" — the preview ran, but its output stayed hidden.
## Capabilities — the full toolbox (pick best-fit per requirement)
You are a **complete** model-driven app builder, not a single-surface tool. Everything below ships in
one App Spec and one build — choose what best serves the user's requirement to make a **useful,
prod-ready** app; don't under-build (a bare table list) or over-build (surfaces nobody asked for):
- **Data model** — tables (give each custom table a **meaningful Fluent-style SVG table icon by default**; propose what the glyph will **depict** in words — never a Fluent token name — and record it as `iconDescription` before drawing the SVG — see [`references/authoring-flow.md`](../../references/authoring-flow.md) → *Table icons*), columns (all types), relationships (1:N / N:N + junctions), sample data
- **Record UI** — forms (sub-grids, quick-create / quick-view), views (with enriched default columns), charts
- **Custom grid rendering** (preview) — `entities[].columns[].visualization`: render a column as a
`RadialDial`, `LineChart`, `HeatMap` or `StarRating` in **every** grid and view that shows it,
instead of plain text. Reach for it when a column is a *magnitude a user scans* (a score, a
utilization %, a rating, a priority) rather than a value they read exactly — it makes a list
scannable at a glance for one line of spec. It is per-*column*, so set it once on the column, not
on each view. **Preview:** on an environment where it is not provisioned the build skips it and
everything else still deploys, so it is always safe to include.
- **Actions** — modern command-bar buttons (incl. flyout / split menus), web resources (form JS / HTML / CSS).
Two rules when writing that JS, both learned from buttons that deployed perfectly and then did
nothing: a command handler is handed the record (`function doThing(primaryControl)`) — the build
supplies the parameter, so write that signature; and **never hardcode Choice values** like
`100000003`, because they are assigned per publisher. Resolve by label via `getOptions()`
(see `references/app-spec-schema-advanced.md` → webResources). Note also that command and web-resource
**edits do not redeploy on rebuild** — the phases reuse what exists, so changing a button or a
script means deleting it first (the build warns, and verify fails, when a web resource's deployed
content differs from the spec's). This does not apply to recovery of the build's own
`WEB_RESOURCE_UNVERIFIED` row: keep that row and the same build workspace, then follow its halt.
- **Form logic without code** — `businessRules[]`: show/hide, lock/unlock, set-required and
set-value, driven by a condition on the record. **Reach for a business rule before form JS** when
the requirement is field-level and declarative — it is visible in the maker, survives solution
export, and needs no web resource. Use form JS when the logic needs a real API call, cross-record
work, or anything beyond the four supported actions.
- **Guided processes** — `businessProcessFlows[]`: the staged bar across the top of a record
(ordered stages, each with steps bound to that table's columns — **every step must bind a `field`**;
the platform rejects one without, so use a Boolean flag for a manual check-off). Reach for one when
the user describes work moving through **phases** — "triage →
investigate → resolve", "lead → qualify → close". Author it `Active` (the default) or the stage bar
does not appear at all. Who may run a flow is `securityRoles: { "personas": [...] }` (Active flows
only). v1 is single-entity and linear: cross-entity stages, branching and stage actions are
**rejected** by the spec gate, so offer Maker for those rather than writing them into the spec.
- **Surfaces** — **generative pages** (modern dashboards / overviews / analytics / landing — the default),
classic dashboards (opt-in), external URLs
- **App shell** — the app module + sitemap, with per-subarea icons. Turn on the **modern shell** with
`app.newLook: true` unless the user asks for the classic one; it is opt-in and best-effort, so a
tenant without the setting still gets a working app. `app.headerNavigationRefresh` controls the
**Wave 2 header/navigation refresh** — a *separate, independent* setting whose platform default is
**ON**, so set it to `false` only when the user explicitly wants the classic header.
- **Security & access** — one **security role per persona**, sized from that persona's jobs-to-be-done
(the entity access each job needs, unioned into the role), so the app **opens for non-admins**.
- **AI-first features** (admin-gated) — form-fill assist, natural-language grid/view search, NL chart
/ AI data visualization, M365 Copilot (opt-in); per-table Copilot row summaries (Insight Cards)
with tailored prompts, auto-selected for good-candidate tables
Author the **smallest spec that fully satisfies the ask**, then let the user refine. The **Genpage-first
policy** below is the record-vs-dashboard rule; [`references/app-spec-schema.md`](../../references/app-spec-schema.md)
documents every field.
## Genpage-first policy (surface classification)
Every app surface is one of two kinds — **enumerate the app's surfaces and classify each one**, don't
decide page-by-page in passing:
- **Record surfaces** (create/read/update/list a table's rows) → a **model-driven form + view**.
- **Everything else** — overview/landing, dashboard, KPIs, analytics, guided or wizard flow,
composite or comparison screen → a **generative page** (`pages[]`), **not** a classic dashboard.
Rules:
- An app whose jobs include an overview, a queue, analytics or a guided flow but which proposes no
pages has missed a surface. Where the app genuinely is record-CRUD only, say so explicitly rather
than silently omitting pages.
- A **traditional `dashboards[]`** is emitted **only on explicit request** (e.g. "use a classic dashboard").
- A generative page is authored as a **design intent** (`source: { kind: "intent" }`,
`schemaVersion: 2`) during Phase 1 — its `.tsx` is written in **Phase 1.5 — Generate pages**, after
plan approval and after the data pre-build creates the tables so `genpage.js types`
can emit `RuntimeTypes.ts`. See [`references/authoring-flow.md`](../../references/authoring-flow.md) → *Pages*.
- The build's `pages` phase writes each page through the SDK and never places it in the sitemap
itself — the SDK is the **single sitemap writer**, so a page's nav entry comes from a
`page` subarea in `appShell` (referenced by the page's **`key`**). See
[`references/app-spec-schema.md`](../../references/app-spec-schema.md) → `pages[]`.
- **Every page in `pages[]` must be sitemap-placed** — validation rejects any page absent from the
sitemap. A "detail" page that receives a caller-supplied id is a normal sitemap page; it reads its
input via `pageInput?.data?.<field>`. Navigation-only (headless) pages are not supported.
- **A page that declares `pageInput` MUST declare `directEntry`.** Because every page is
sitemap-placed, a detail page is also reachable straight from the app navigation with **no input**
— a state a user reaches by clicking. Say what happens then: `{ "behavior": "selector" }` shows a
picker and then the record, `{ "behavior": "emptyState" }` explains and renders nothing broken.
Prefer `selector` when the table is browsable; it is the more useful landing. Every key in
`pageInput.data` must also be produced by some page's `navigatesTo[].data`, or the generated page
reads a key nothing ever sets.
- **Three-authority page identity** (build + download + verify all follow this): (1) **IDENTITY** —
the durable `<app>_pagemanifest` (`key → pageId`); a downloaded spec's own `pages[].pageId`
outranks it for that rebuild. (2) **EXISTENCE** — the env-wide page list read through the SDK, drafts
included (crash-safe; decides create-vs-reuse). (3) **MEMBERSHIP** — the app's sitemap `GenPageId` set (placement,
download enumeration, verify coverage). All matching is by id — never by display name.
- **Multi-page navigation uses `PAGEREF_<key>`** (the stable `pages[].key`) as the `pageId`
placeholder; the build resolves each to the real page GUID in a run-scoped staging copy (the
canonical `.tsx` is never mutated), then **verifies every nav edge** resolves to the deployed
page's `GenPageId`.
## Workflow
### Phase 0 — Working directory
1. Derive a short kebab-case slug from `$ARGUMENTS` (e.g. "Project Tracker" → `project-tracker`).
2. Create the directory (`mkdir -p <slug>` on bash/PowerShell; `mkdir <slug>` on cmd, which has no
`-p` and errors if it exists) and resolve its absolute path. It holds `app-spec.json`,
`model-app-plan.md`, and `workflow-log.md`.
### Phase 1 — Author the App Spec (interactive, main loop)
Follow **[references/authoring-flow.md](../../references/authoring-flow.md)** step by step, running
every prompt yourself via `AskUserQuestion`. In short:
#### Unattended runs (Copilot autopilot / automation)
Resolve the interaction mode once before the first authoring question:
```bash
node "${PLUGIN_ROOT}/scripts/resolve-interaction-mode.js" [--non-interactive]
```
`POWER_PLATFORM_SKILLS_NONINTERACTIVE=1`/`true` (or the equivalent
`--non-interactive` invocation) means there is no user waiting for prompts. In
that mode:
- do not call `AskUserQuestion`, `EnterPlanMode`, or `ExitPlanMode`;
- use explicit requirements and supplied existing specs as authoritative, and
use documented defaults only where the request leaves a non-destructive
choice open;
- record each skipped gate as
`Unattended default: <question> → <answer> (<reason>)` in `workflow-log.md`;
- treat the completed lint, preview, rendered design document, and build dry-run
as the approved plan, then continue with the normal approved path;
- halt rather than guessing an ambiguous environment, app identity, or
destructive structural edit.
Suppressing interaction never authorizes destructive work. An unattended
existing-app apply still requires `--allow-destructive` wherever the build
normally requires it; `POWER_PLATFORM_SKILLS_NONINTERACTIVE` only suppresses
prompts.
Carry the resolved mode through subprocesses: when it is unattended, append
`--non-interactive` to every `build-model-app.js` invocation (dry-run, data
pre-build, recovery rerun, and full apply). Do not append `--allow-destructive`
unless destructive authority was supplied independently.
1. **Prereqs** — `node --version`, `pac help` (> 2.10.0, the plugin's minimum).
2. **Environment (PAC)** — `pac auth list`. If exactly one / an active profile, **confirm it
(FYI), don't ask**. If several and none active, **ask** which to use. If none, ask the user
to `pac auth create`. Capture the org URL (`pac org who`).
3. **Detect existing** — `scripts/list-tables.js --env <envUrl> --search … --exact` and
`scripts/apps.js list --env <envUrl>` (`<envUrl>` is the org URL from step 2) to find
tables/apps already present; build *around* them. `--exact` keeps only the tables whose
logical name is a search term and lists the terms with none in `missing`. A failed read
(exit 1) is reported and ends the step — never read it as "nothing exists".
4. **Levelled authoring** — **first read the App Spec format** so you author to the exact
shape (do this once; don't go spelunking through scripts):
[`references/app-spec-schema.md`](../../references/app-spec-schema.md) and the worked sample
[`samples/app-spec.support-desk.json`](../../samples/app-spec.support-desk.json). That document
covers everything an app always has. **Additionally read
[`references/app-spec-schema-advanced.md`](../../references/app-spec-schema-advanced.md) once your
design calls for a conditional feature** — business rules, a business process flow, command-bar
buttons, web resources, global choices, classic dashboards, or `roleGrants[]`. Its pointer table
is in the main schema, and the toolbox above tells you when to reach for each; read the detail
only for the ones you are actually using, and never skip a capability just to avoid the read.
Phase 1 is
**design-only**: never emit page `.tsx` here. Each level is confirmed via `AskUserQuestion` before
the next begins, and `app-spec.json` is persisted after each — full prompts in the playbook.
- **Level (a0) — personas & jobs-to-be-done** (`personas[]`): **before proposing any tables**, ask
who will use the app and what each needs to get done. Jobs drive everything that follows — a
table exists because a job needs its data, a surface because a job needs to act on it. Deriving
the data model first reliably misses surfaces. Privileges come later; capture the jobs now.
- **Level (a) — data model**: entities/columns/relationships **derived from those jobs**; run the
**early data-model lint** (catches e.g. the relationship-vs-lookup collision before forms are
authored on top).
- **Descriptions are part of authoring, not a cleanup pass.** Every table, column, view, chart,
form, dashboard and business rule takes an optional `description`, and you should **write one as
you create the artifact** — never as a backfill. A name says what a thing is called; a
description says what it is *for*, and it is the only intent an app carries that an agent can
read back later when it inspects an app it did not build. Describe the purpose, not the shape:
`"Severity 1-5; drives the escalation rule and the SLA clock"`, not `"The priority column"`.
(`commands[]` and `Customer` columns accept one but the SDK cannot write it — you'll get a
warning; `personas[]` does not take one at all. See the schema reference for why.)
The app itself takes two: `app.description` is the short tile text, and `app.aiDescription` is
the **routing description** an orchestrator reads to choose between apps — who the app is for,
what it covers and excludes, and how to tell it from a sibling app over the same tables. Write
it whenever such a sibling exists or is planned.
- **Level (b) — artifacts + page-intents + design**: **enumerate every surface each job needs and
classify it** per the genpage-first policy above — record CRUD → form + view; anything else
(overview/landing, dashboard, KPIs, analytics, guided/wizard flow, composite or comparison
screen) → a page **intent** (`source: { kind: "intent" }`). State each classification out loud;
if the app needs no pages, say so and why rather than silently omitting them. Then forms + views
+ charts + sample data and the optional `design` contract, mapping each job to its surfaces via
`jobs[].surfaces[]`. **No page `.tsx` here.** `dashboards[]` only on explicit request.
- **Level (c) — access** (`personas[].jobs[].privileges[]`): personas and jobs already exist from
(a0) and the entities now exist, so **only add the privileges each job needs** — don't re-ask who
the users are. The builder unions them into one role per persona and grants the app to it so it
**opens for that persona, not just sysadmins**. **Render the roles + per-entity access as a table
in your chat reply** (the user can't approve an access model they can't see — see the CRITICAL
note above). If they want no roles, tell them jobs live in `personas[]` so dropping the roles
drops the recorded jobs too; offer read-only privileges to keep the record. (Column-level
security and access teams are not yet supported — see *Notes & limits*.)
- **Whole-app preview** (design gate for Level (b)): `node "${PLUGIN_ROOT}/scripts/preview-app.js" --spec @<working-dir>/app-spec.json`
renders data-model + sitemap + form wireframes + page-intents + design contract. **Reproduce the
ENTIRE rendered output verbatim in your chat reply, inside a fenced ` ``` ` code block — do NOT
leave it in the (collapsed, invisible) tool output, and do NOT just summarize "the preview looks
right" (see the CRITICAL note above).** The user must be able to SEE each form, the sitemap, and
the page intents they are approving. For a single form only: `node "${PLUGIN_ROOT}/scripts/preview-form.js" --spec @<working-dir>/app-spec.json`.
- **Don't pre-create tables/columns** — the build does it idempotently.
5. **Guardrail lint (hard gate)** — run the **full** lint on the complete spec; **errors block**, warnings teach. If it blocks (or warns), **paste the findings into your chat reply** — tool output is collapsed and invisible to the user (see the CRITICAL note above), so the user can't fix what they can't see:
```bash
node "${PLUGIN_ROOT}/scripts/lint-app-spec.js" --spec @<working-dir>/app-spec.json --json
```
This runs migration and `validateAppSpec` — the gates the build itself runs on load — plus the `lintAppSpec` authoring guardrails, which the builder does **not** run. It exits non-zero on errors. It validates under the `plan` profile (which allows not-yet-generated intent pages), matching Step 6's dry run.
6. **Plan-mode approval (the single build approval)** — present the plan **including the build
dry-run's phase-grouped plan** (run `build-model-app.js` without `--apply`, using the `plan`
profile that allows intent pages) inside `EnterPlanMode`, then `ExitPlanMode` to get the user's
go-ahead. On approval, **Phase 1.5** (generate-pages) runs first, then **Phase 2** applies
directly (no second dry-run/go-ahead). Render the design document — never hand-write it:
```bash
node "${PLUGIN_ROOT}/scripts/write-app-spec-doc.js" --spec @<working-dir>/app-spec.json --env <envUrl>
```
It writes `<working-dir>/model-app-plan.md` (jobs → surfaces traceability, data model, every
surface, navigation, access model, sample data) and prints `{ ok, docPath, bytes, warnings }`.
**Surface those `warnings`** — they name design gaps such as a job with no covering surface, an
app with no generative pages, or a new table that no persona and no `roleGrants[]` entry grants a
privilege on. With `--env` the document also lists, read-only, the roles the app already has
associated with it, apart from the privileges on the tables the spec adds (opening the app and using
a table are two questions); a read that fails is reported in the document as "not checked" and does
not fail the command. Tell the user where the document is; it's theirs to keep, and it's
regenerable after any spec edit.
### Phase 1.5 — Generate pages (main loop, headless workers)
After plan-mode approval (before the full build):
1. **Data pre-build** — schema-only build so `genpage.js types` can resolve real column names:
```bash
node "${PLUGIN_ROOT}/scripts/build-model-app.js" \
--env <envUrl> --spec @<working-dir>/app-spec.json --stage data --apply
```
`--stage data` applies solution + data-model only — **no `--sample-data`** (rows are created
once in the full build). Only `--stage data` is apply-safe; all other `--stage` selectors
and legacy `--from/--to/--only/--skip` selectors are dry-run inspection only.
2. **Types** — generate Dataverse type bindings for the entities the pages read:
```bash
node "${PLUGIN_ROOT}/scripts/genpage.js" types --env <envUrl> --data-sources "<entity1,entity2,…>" --output-file <working-dir>/RuntimeTypes.ts
```
`--data-sources` is the union of every intent page's `dataSources`. Skip this step entirely when
every intent page is mock-only. On Windows use forward slashes in the path. The script prints
`{ "ok": true, "outputFile", "dataSources", "detail", "bytes" }`; a failure (exit 1, `"ok": false`)
stops the step — report why, since the page workers must not guess column names.
3. **Page plan (adapter)** — the page worker's input contract is a *plan document*, not an App Spec,
so project the spec into one. This also echoes the per-page dispatch parameters:
```bash
node "${PLUGIN_ROOT}/scripts/write-page-plan.js" \
--spec @<working-dir>/app-spec.json --working-dir <working-dir> --env <envUrl> \
--app "<app name>" --languages "<languages from the environment probe>"
```
It writes `<working-dir>/app-builder-page-plan.md` and prints
`{ ok, planPath, pages: [{ name, key, file, dataMode, intent }] }`. Pass `--languages` through
from the environment probe — omitting it silently defaults every plan to English-only and drops
the localization pattern. The command fails (before writing) if the plan would name a sample that
doesn't exist, or if a page a worker will write is not a safe target in the working directory — a
link at its path, a folder that links outside the directory, or a page already there under another
spelling — or if a link, a hard link or a folder is already at the plan's own path. Stop and fix
what it names; do not dispatch any worker.
4. **Generate** — for each page from step 3 with `intent: true`, dispatch the **headless**
`genpage-page-builder` worker via `Task`. Use its documented input contract verbatim — a missing
field is why a page silently never becomes `.tsx`:
> You are the genpage-page-builder agent. Generate the **[name from step 3]** page.
>
> - Target file: [file from step 3 — already includes .tsx; do NOT append another]
> - Plan document: [absolute path to the app-builder-page-plan.md written in step 3]
> - Data mode: **[dataMode from step 3 — `dataverse` or `mock`]**
> - Connectors: **none**
> - Telemetry: **disabled**
> - RuntimeTypes: [absolute path to RuntimeTypes.ts] ← omit this line when Data mode is `mock`
> - Working directory: [absolute working-dir path]
> - Plugin root: ${PLUGIN_ROOT}
>
> Follow the instructions in your agent file. Write [file] and return your result when done.
The plan's `## Environment` carries `Mode: app-builder` and every page row carries a **Key**, so
the worker emits `"PAGEREF_<key>"` for cross-page navigation (never a file-derived token — a
downloaded page's `codeFile` is a path, not its identity). Custom nav ids go in `data:` — never
`recordId`. `Connectors: none` and `Telemetry: disabled` are constants here: `/app-builder` writes no
connector code (the App Spec's `connectorBindings` / `actionBindings` are lists a downloaded page already
holds, carried through a rebuild and never authored here, so the projected plan always says
`No connector bindings.`), and `/app-builder` never runs the Phase 4.7 `custom-telemetry` probe. Both are stated explicitly
rather than omitted — the page-builder treats a missing line as the same fail-closed value, but
an explicit line is what makes the dispatch contract checkable.
5. **Check styles, then validate + commit the transition (transactional)** — the workers have no
shell, so first check every generated page for the Griffel shorthands that `makeStyles` drops at
runtime, one command per page (`<file>` is the page's file from step 3):
```bash
node "${PLUGIN_ROOT}/scripts/check-griffel-styles.js" --file <working-dir>/<file>
```
Griffel does not support ten CSS shorthands, and `makeStyles` drops them at runtime: the page
type-checks, transpiles and deploys, then renders without the border, color or reset. They are
`all`, `borderColor`, `borderStyle`, `borderWidth`, `borderBlock`, `borderBlockStart`,
`borderBlockEnd`, `borderInline`, `borderInlineStart` and `borderInlineEnd`. Write longhands
instead: `borderColor`, `borderStyle` and `borderWidth` become one longhand per side, `border` +
`Top`, `Right`, `Bottom` or `Left` + `Color`, `Style` or `Width` (`borderWidth` →
`borderTopWidth`, `borderRightWidth`, `borderBottomWidth`, `borderLeftWidth`); `borderBlock`,
`borderInline` and their `Start` and `End` forms become the `Width`, `Style` and `Color` longhands
of the sides they name (`borderBlockStart` → `borderBlockStartWidth`, `borderBlockStartStyle`,
`borderBlockStartColor`; `borderBlock` → those and the three `borderBlockEnd…` ones); `all` has no
longhands, so set the properties you need one by one. Every other shorthand (`padding`, `margin`,
`border`, `borderRadius`, `gap`, `outline`) is supported, and an inline `style={{ … }}` is not
Griffel at all.
`check-griffel-styles.js` prints each problem it finds — a key Griffel drops in a `makeStyles`
call, at any depth, with its line, column and longhands, or a call or a style object it cannot
read, with what to change — and exits 3 while any is left: fix what it reports and run it again,
and do not transpile or upload the page until it exits 0. It reads the style objects written
inline in the call, `makeStyles({ … })`, so write them there: one passed or spread in from
elsewhere (`makeStyles(styles)`, `...base`) is reported, because the check cannot see its keys,
and so is a key computed from an expression (`[key]: …`), whose name it cannot see (a template
that starts with `--`, `&`, `:` or `@` is read); Fluent's `...shorthands.*(…)` and
`...typographyStyles.*` may be spread as they are.
Review every generated page for iteration that compiles to nothing as well:
The page compiler targets ES5 without iterator downleveling or full type checking. Spreading,
looping over, or array-destructuring a Map, Set or iterator reads length and indices instead of
the iterator: values can disappear, defaults can replace them, or rest destructuring can throw.
This includes `[...new Set(xs)]`, `[...m.values()]`, `[...seen.values()]`,
`for (const [k, v] of m)`, `new Set([...prev, id])`, `[...selected]` and
`[...text.matchAll(re)]`. Convert with `Array.from(...)` before spreading, looping or
destructuring; copy a Set with `new Set(prev)` then `.add(id)`. Ordinary array spreads and loops
remain valid. `Object.keys`, `Object.values` and `Object.entries` return arrays. Spreads of
`arguments` and ordinary indexed array-likes work; rest destructuring of an array-like without
`slice` does not. String spread throws, and an ES5 string loop visits...
© Microsoft Corporation · MIT · microsoft/power-platform-skills
Похожие скиллы
Все скиллы по теме «Настройка агента: память, контекст, субагенты» →Сначала — app-builder от других авторов.