add-ai-webapi — скилл для Claude Code: что делает и как установить
Скилл add-ai-webapi встраивает preview-интерфейсы суммаризации Power Pages в SPA-сайты. Генерирует клиентский код вызова API и параметры сайта.
MIT ★ 1 167 обновлён 2026-10-29
/plugin marketplace add microsoft/power-platform-skills
/plugin install power-pages@power-platform-skillsЧто делает add-ai-webapi
Скилл генерирует код слоя суммаризации для клиентских приложений Power Pages. Он работает с двумя интерфейсами: Search Summary API (POST /_api/search/v1.0/summary) для сводок поисковой выдачи и Data Summarization API (POST /_api/summarization/data/v1.0/<entitySet>(<id>)) для формирования выжимок по отдельным записям Dataverse. Решение создаёт функции с передачей CSRF-токенов и выставляет параметры сайта группы Summarization/*.
Базовые разрешения таблиц и роли делегируются скиллам /integrate-webapi и /create-webroles. Сам add-ai-webapi отвечает только за третий слой — код сервиса суммаризации и специфичные для ИИ параметры. Агент интеграции запускается последовательно для каждой сущности, формируя общий сервисный файл.
Административная иерархия включает три уровня: настройку PowerShell на уровне тенанта enableGenerativeAIFeaturesForSiteUsers, политики среды в Copilot Hub и переключатель в настройках сайта. Без включения на уровне тенанта API вернёт ошибку даже при активном чекбоксе в студии сайта.
Какие задачи решает
- добавить краткую ИИ-выжимку по обращению или инциденту на страницу портала
- настроить вызов Search Summary API с передачей CSRF-токена в кастомном интерфейсе
- прописать параметры конфигурации сайта из группы Summarization
- создать клиентский слой для суммаризации таблиц Dataverse в SPA
Примеры запросов агенту
- Добавь краткую ИИ-сводку для карточки обращения в нашем одностраничном приложении.
- Сгенерируй код вызова API поиска с генеративной сводкой для кастомного поискового экрана.
- Подключи суммаризацию данных по таблице инцидентов и настрой нужные параметры сайта.
Как установить add-ai-webapi
1Через маркетплейс плагинов
/plugin marketplace add microsoft/power-platform-skills/plugin install power-pages@power-platform-skillsКоманда ставит плагин power-pages целиком, со всеми его скиллами
2Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill add-ai-webapi -a claude-code3Вручную: положить файлы
~/.claude/skills/add-ai-webapi/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/add-ai-webapi/
1Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill add-ai-webapi -a codex2Вручную: положить файлы
.agents/skills/add-ai-webapi/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill add-ai-webapi -a cursor2Вручную: положить файлы
.cursor/skills/add-ai-webapi/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install microsoft/power-platform-skills plugins/power-pages/skills/add-ai-webapi2Вручную: положить файлы
.github/skills/add-ai-webapi/SKILL.md1Через Skills CLI (Vercel)
npx skills add microsoft/power-platform-skills --skill add-ai-webapi -a gemini-cli2Командой платформы
gemini skills install https://github.com/microsoft/power-platform-skills --path plugins/power-pages/skills/add-ai-webapiВручную: положить файлы
.devin/skills/add-ai-webapi/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы об add-ai-webapi
Как установить add-ai-webapi в Claude Code?
Сначала добавьте каталог плагинов: /plugin marketplace add microsoft/power-platform-skills. Затем выполните установку: /plugin install power-pages@power-platform-skills.
Что делает скилл add-ai-webapi?
Он создаёт клиентский код вызовов Data Summarization API и Search Summary API в Power Pages, а также настраивает параметры Summarization/*.
Почему API суммаризации сообщает об отключении?
Доступ регулируется трёхуровневой иерархией. Если параметр enableGenerativeAIFeaturesForSiteUsers выключен на уровне тенанта или ограничен в Copilot Hub, включение на уровне сайта не сработает.
Исходный текст
SKILL.md · MIT
---
name: add-ai-webapi
description: >-
Integrates Power Pages generative-AI summarization APIs (PREVIEW) into a Single Page Application
(SPA) site — the Search Summary API and the Data Summarization API — on any record-detail or list
page. Generates per-target service code (CSRF-handled) and AI site settings; delegates Web API
settings, table permissions, and web roles to `/integrate-webapi` and `/create-webroles`. Use
whenever a user wants AI/Copilot output that condenses Dataverse content on a Power Pages site —
an AI summary, AI-generated overview or "key insights" across a record or list, a search-results
summary, a case/incident summary, or recommendation-chip refinement — even when phrased as
"AI-generated paragraph", "insights", or "overview". Do NOT use for: generative pages in
model-driven apps (use the model-apps `genpage` skill), Copilot Studio agents/chatbots,
summarizing documents or PDFs, Power BI dashboards, plain keyword search with no AI summary, or
plain Dataverse CRUD (use `/integrate-webapi`).
user-invocable: true
argument-hint: Optional description of which pages/tables need AI capabilities
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Skill, Task, TaskCreate, TaskUpdate, TaskList, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch
model: opus
---
> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.
# Add AI Web API
> **Note**
>
> AI summarization APIs are a preview feature. Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.
**Surface this note to the user verbatim** during Phase 1 and again in the Phase 8 summary —
copy the exact `**Note**` block above (including its wording about "available before an official
release so that customers can get early access and provide feedback"). Do not paraphrase it into
your own "Preview-feature note: ..." sentence; the wording matches the Microsoft Learn preview
disclaimer and rephrasing it loses that fidelity.
Integrate Power Pages generative-AI summarization APIs into a SPA site. This skill focuses on the AI layer (Layer 3): the summarization service code and the `Summarization/*` site settings. The underlying Web API prerequisites — `Webapi/<table>/enabled`, `Webapi/<table>/fields`, table permissions, and web roles — are **delegated** to `/integrate-webapi` and `/create-webroles` so there is a single source of truth for every layer.
## The two APIs covered
| # | API | URL | Body | Response |
|---|-----|-----|------|----------|
| 1 | **Search Summary** | `POST /_api/search/v1.0/summary` | `{ userQuery }` | `{ Summary, Citations }` |
| 2 | **Data Summarization** | `POST /_api/summarization/data/v1.0/<entitySet>(<id>)?$select=...&$expand=...` | `{ InstructionIdentifier }` or `{ RecommendationConfig }` | `{ Summary, Recommendations }` |
> **Example: Microsoft-shipped Copilot summary on a support-case page.** Data Summarization can be
> called with any combination of entity set, columns, and prompt — but Microsoft documents and
> ships one specific configuration for the standard `incident` table:
> `POST /_api/summarization/data/v1.0/incidents(<caseId>)?$select=description,title&$expand=incident_adx_portalcomments($select=description)`
> with body `{ "InstructionIdentifier": "Summarization/prompt/case_summary" }`. This is sometimes
> called the "Case-page Copilot preset" in Microsoft Learn. Treat it as one possible Data
> Summarization recipe — useful when the user explicitly wants to mirror the Microsoft sample —
> not as an automatic recommendation. A custom case-like table (`cr363_servicerequest`,
> `adx_case`), or the standard incident table summarised on different facets (priority, owner,
> SLA timer), is just a regular Data Summarization call with maker-defined values.
> Reference: `${PLUGIN_ROOT}/skills/add-ai-webapi/references/ai-api-reference.md` — canonical
> API shapes, required headers, site-setting names, error codes, and the documented support-case
> example. Read this at the start of the workflow; fetch the Microsoft Learn source pages with
> `mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch` if the user asks for the latest.
> **Admin governance hierarchy**: both APIs are gated by a **three-level admin
> hierarchy** — tenant PowerShell setting (`enableGenerativeAIFeaturesForSiteUsers`), Copilot Hub
> environment/site governance, and the site-level maker toggle (for Search Summary: Set up
> workspace → Copilot → Site search (preview) → Enable Site search with generative AI (preview)).
> **Each level overrides the one below it**, so "the maker toggle is on but the API still says
> disabled" is a real scenario — admin-level governance wins.
>
> The two endpoints surface disablement differently:
>
> - **Search Summary** → HTTP **200** with an embedded envelope `{ Code: 400, Message: "Gen AI
> Search is disabled." }`. The generated `fetchSearchSummary` detects this and throws
> `SearchSummaryApiError`; the UI renders a remediation card.
> - **Data Summarization** → HTTP **400** with `error.code = 90041001` (admin-level disabled) or
> `90041003` (per-site `Summarization/Data/Enable=false`).
>
> Full troubleshooting checklist (tenant → environment → site, plus runtime version, Bing
> dependency, and cross-region data movement) lives in
> `references/ai-api-reference.md` §1 "Troubleshooting: AI feature appears disabled (admin
> hierarchy)" — point users there when either disablement shape surfaces. Mention this governance
> hierarchy explicitly to the user before Phase 7, and again in the Phase 8 summary.
> **Built-in search control vs. custom code path**: if the site uses the Microsoft-shipped Power
> Pages search **control** and only wants AI-summarised search results on that page, they don't
> need this skill — just the Copilot workspace toggle and the `Search/Summary/Title` content
> snippet. This skill is for sites that build their own search UI or need to call
> `/_api/search/v1.0/summary` from custom code. Confirm which path the user is on in Phase 1.
## Core principles
- **Layer 3 only, delegate the rest.** Web API site settings, table permissions, and web roles all belong to `/integrate-webapi` and `/create-webroles`. This skill creates the summarization service code and the `Summarization/*` site settings — nothing else.
- **Sequential agent spawning.** Per `plugins/power-pages/AGENTS.md`, spawn the `ai-webapi-integration` agent sequentially per target (never in parallel). The first call establishes the shared summarization service file and CSRF helper; subsequent calls extend it. `ai-webapi-settings-architect` runs alone, after all code integrations land.
- **Raw `fetch` + CSRF.** Every summarization request attaches `__RequestVerificationToken` (from `/_layout/tokenhtml`) and `X-Requested-With: XMLHttpRequest`. Never route through an OData wrapper.
- **Skip `/integrate-webapi` when it's not needed.** If every confirmed target is Search Summary (which has no per-table Web API prerequisites), or every Layer 1/2 prerequisite already exists on disk, the skill goes straight from Phase 3 to Phase 5.
- **Use TaskCreate/TaskUpdate** — create the todo list upfront with all phases before starting.
- **Preserve site integrity.** Before adding or tweaking an AI surface, read `${PLUGIN_ROOT}/references/site-modification-integrity.md`; localization covers labels, loading, empty, error, citation, recommendation, and remediation states, and the UI must remain bidirectional and expansion-safe.
> **Prerequisites:**
>
> - An existing Power Pages SPA site created via `/create-site`
> - A Dataverse data model (tables + columns) set up via `/setup-datamodel` or manually — for any
> Data Summarization target
> - The site must have been deployed at least once (`.powerpages-site` folder must exist) for the
> settings phase
**Initial request:** $ARGUMENTS
---
## Workflow
(Phase headings below the workflow keep the technical "Layer 1+2 / Layer 3" names because they
describe the runtime layering and are what maintainers grep for. The titles here mirror the
user-facing task list.)
1. **Check site is ready** — locate project, detect framework, check data model, deployment status, and web-role presence.
2. **Find where AI summaries fit** — scan code for search / data summarization candidates.
3. **Confirm what to add** — review the manifest and pick which APIs / targets to integrate.
4. **Set up data access for AI** — invoke `/create-webroles` if needed, then invoke `/integrate-webapi` in AI-only read mode for data/case targets. Skip entirely for search-only or when prerequisites already exist.
5. **Add AI summary code** — invoke the `ai-webapi-integration` agent sequentially per target.
6. **Register AI prompts** — invoke the `ai-webapi-settings-architect` agent.
7. **Verify everything** — header-contract grep, `$select` grep, `npm run build`, validator script.
8. **Review and deploy** — record skill usage, summarise, offer `/deploy-site`.
---
## Iteration mode (after first run)
This skill is a **one-shot setup skill** — Phases 1–8 run end-to-end the first time the user asks
to integrate a summarization API. Once an AI surface is in place (service file, framework wrapper,
UI call site, and `Summarization/*` settings all exist), follow-up requests to tweak the rendered
UI (colours, spacing, copy, moving a button, a different empty-state message, wiring a second
recommendation into the hook, etc.) are **not** a reason to re-enter this skill mentally and run
every phase again. Doing so triggers a full `pac pages upload-code-site` and a chain of
`git commit`s for each tweak, which is exactly the noisy cadence the Phase 5.5 / 6.4 prompts above
are there to avoid.
When the user asks for follow-up UI changes to an already-integrated AI surface:
- **Edit the file(s) and run `npm run build`** locally to verify the tweak compiles. That is the
whole validation loop for a UI change.
- **Do NOT automatically run `pac pages upload-code-site`.** Uploading should happen once, at the
end of the session, when the user has finished tweaking.
- **Do NOT automatically `git commit`.** Let the user batch related tweaks into a single commit.
- **Batch the deployment and commit into a single end-of-session prompt** once the user signals
they're done (or when you've completed the last requested change).
<!-- gate: add-ai-webapi:iter.deploy-commit | category=consent | cancel-leaves=nothing -->
> 🚦 **Gate (consent · add-ai-webapi:iter.deploy-commit):** End-of-iteration batched deploy + commit prompt — avoids a noisy per-tweak upload/commit cadence.
>
> **Trigger:** User signals they're done with UI tweaks for the session.
> **Why we ask:** Auto-deploying or committing after every small edit produces one `git commit` + one `pac pages upload-code-site` per tweak; batching keeps history readable and avoids redundant deploys.
> **Cancel leaves:** Nothing — source files already edited; no deploy or commit fired.
Use `AskUserQuestion`:
| Question | Header | Options |
|----------|--------|---------|
| All the UI tweaks look good. Deploy the site and commit the changes now? | Deploy & commit | Yes, deploy and commit (Recommended), Just commit — I'll deploy later, Just deploy — I'll commit later, Neither — I'll handle both myself |
Re-enter the full skill flow only when the user is adding a **new** AI surface (a new page, a new
table, a second API). If you're unsure whether a request is a tweak or a new surface, ask.
---
## Phase 1: Verify Site Exists
**Goal**: Locate the Power Pages project root and confirm prerequisites.
### 1.0 Detect iteration mode (before anything else)
Re-entry detection comes first because the rest of the skill assumes a first-time setup.
Capture two signals about the project state:
1. **Service signal**: a summarization service exists — `src/services/aiSummaryService.*`, or any
source file under `src/` that contains `/_api/search/v1.0/summary` or
`/_api/summarization/data/v1.0/`. When the signal is present, also note which API surface(s)
the service code references — search-only, data-only, or both. This sub-classification matters
below.
2. **Settings signal**: at least one Layer 3 site setting exists in
`.powerpages-site/site-settings/Summarization-*.sitesetting.yml`.
Then route on the combination:
- **Both signals present** → re-entry. A previous `/add-ai-webapi` run completed end-to-end. Show
the iteration-mode prompt below.
- **Service signal present and the existing service code is search-only** (it references
`/_api/search/v1.0/summary` but **not** `/_api/summarization/data/v1.0/`) → re-entry. Search-only
sites legitimately have no `Summarization/*` settings (Search Summary uses the workspace toggle,
not per-call settings), so the absence of the settings signal is the steady state, not a
failed run. Show the iteration-mode prompt below.
- **Service signal present and the existing service code includes Data Summarization** but the
settings signal is absent → in-flight first run (a previous attempt failed before Phase 6
landed). Continue with the full flow without prompting.
- **Neither signal present** → first-time run. Continue with Phase 1.1.
When you reach the iteration-mode branch, ask:
| Question | Header | Options |
|----------|--------|---------|
| It looks like an AI summary surface is already wired into this site. Is this request a tweak to the existing one, or are you adding a brand-new surface (new page, new table, second API)? | Mode | Tweak the existing surface (Recommended for visual/copy edits), Add a new surface (run the full skill again), Not sure — show me what's already wired |
- **Tweak the existing surface**: stop running this skill. Switch into the workflow described in
the [Iteration mode](#iteration-mode-after-first-run) section above — Edit + `npm run build`,
no auto upload-code-site, no auto commit, batched end-of-session prompt for deploy + commit.
- **Add a new surface**: continue with Phase 1.1 (full flow). The downstream phases will detect
existing infrastructure (CSRF helper, summarization service, settings) and extend rather than
duplicate.
- **Not sure — show me what's already wired**: list the existing service file(s), wired UI
components, and `Summarization/*` settings, then re-ask the same question.
### 1.1 Create todo list
Create all 8 phase tasks upfront via `TaskCreate` — see [Progress Tracking](#progress-tracking).
### 1.2 Locate project
Look for `powerpages.config.json` in the current directory or immediate subdirectories.
**If not found**: tell the user to create a site first with `/create-site`.
### 1.3 Detect framework
Read `package.json` and detect React / Vue / Angular / Astro. See
`${PLUGIN_ROOT}/references/framework-conventions.md`.
### 1.4 Check for data model
Look for `.datamodel-manifest.json`. If found, read it — tables listed here are candidates for the
Data Summarization API. The standard `incident` table is a candidate like any other; do not
treat it specially.
### 1.5 Check deployment status — hard prerequisite
Look for `.powerpages-site`. Phase 4 (`/integrate-webapi`) and Phase 6 (`ai-webapi-settings-architect`)
both require this folder to exist. Deferring the deploy until later is **not** a viable workaround:
once Phase 5 has written the AI-calling service code, deploying a site whose Layer 1/2/3 settings
aren't yet on disk publishes runtime-broken code (every summarization call 403/500s until a second
deploy lands). The cleanest sequence is to deploy the **clean scaffold** now, before any AI code
exists.
**If `.powerpages-site` does NOT exist:**
| Question | Header | Options |
|----------|--------|---------|
| `.powerpages-site` was not found. The AI summary skill needs the site deployed at least once before configuring permissions and settings. Deploy the clean scaffold now (no AI code yet — keeps the intermediate state safe), or stop and run `/deploy-site` yourself first? | Bootstrap deploy | Yes, deploy the scaffold now (Recommended), Stop — I'll deploy first then re-run /add-ai-webapi |
On **Yes**: invoke the `Skill` tool for `power-pages:deploy-site` and wait for completion. Then
re-check `.powerpages-site` exists before proceeding. **If it is still absent** after the
sub-skill returns (deploy failed mid-flow, the user cancelled it, or an upload completed but the
local folder wasn't created), stop here with a clear message — surface the deploy-site outcome
verbatim so the user can debug it, and tell them to re-run `/deploy-site` followed by
`/add-ai-webapi`. Do NOT silently fall through to Phase 2; the downstream sub-skills require this
folder.
On **Stop**: end the skill with a clear next-step message ("Run `/deploy-site`, then re-invoke
`/add-ai-webapi` to continue"). Do NOT continue to Phase 2 — the downstream sub-skills can't run.
### 1.6 Check web roles
Look for `.powerpages-site/web-roles/*.yml`. Record whether any roles exist — the Phase 4
delegation needs at least one role before `/integrate-webapi` can create table permissions.
**Output**: confirmed project root, framework, data-model availability, deployment status, web-role inventory.
---
## Phase 2: Explore AI integration points
**Goal**: Find every candidate for each of the two APIs — scoped to AI only.
The full Explore-agent prompt body, manifest shape, and delegation-decision rules live in
`${PLUGIN_ROOT}/skills/add-ai-webapi/references/explore-prompt.md`. Read that file
first, then invoke the **Explore agent** (via `Task` with `subagent_type: "Explore"`,
thoroughness `medium`) and pass the prompt body verbatim.
What the Explore agent reports back (summary — see the reference for the exact prompt):
- **Reserved-slot markers** (`POWERPAGES:AI-SLOT kind=<pick>`) — authoritative placement hints
planted by `/create-site`; orphan markers are flagged for Phase 3 to resolve.
- **Search Summary candidates** including related-record-discovery targets on detail pages
("suggested KB articles", "similar cases").
- **Data Summarization candidates** classified `single-record` / `list` / `intent-mismatch`,
each with the existing fetch's OData query and a scope classification
(`matches-existing-fetch` / `scope-extends-beyond-existing-fetch` / `needs-definition` /
`intent-mismatch`).
- **Existing infrastructure** — CSRF helper, `powerPagesApi.ts`, prior `aiSummaryService.*`.
- **Layer 1/2 status** per Data Summarization target plus every `$expand` target —
`ready` / `missing` / `n/a (search)`.
- **Fields-list breadth advisory** — for Layer 1/2 `ready` rows whose existing
`Webapi/<table>/fields` is broader than the AI surface needs (primary key included, relationship
Navigation Properties unused by `@odata.bind`, unused columns), flagged `fields-broader-than-ai-mode` so Phase 3 can surface
it.
- **Layer 3 status** per Data Summarization target — `Summarization/Data/Enable` and the
specific `Summarization/prompt/<id>` the code will send.
Compile the integration manifest from the agent's output (one row per candidate, columns:
`#`, `API`, `Target file`, `Target kind`, `Entity Set`, `$select` / `$expand`, `Source`,
`Layer 1/2 status`, `Layer 3 status`) — the reference file contains a worked example.
**Delegation decisions** (compute directly from the status columns):
- Run `/integrate-webapi`? → True if any row's Layer 1/2 status is `missing`. Send only the
missing-status rows in the `tables=` sentinel; don't re-audit settled tables.
- Run `ai-webapi-settings-architect`? → True if any row's Layer 3 status is `missing`.
**Output**: integration manifest + delegation decisions + existing-infra report +
fields-broader-than-ai-mode advisory list (if any).
---
## Phase 3: Review AI plan
**Goal**: Present the manifest and confirm which APIs / targets to integrate.
Show the user:
1. The list of APIs and targets found.
2. For each: which file references it and what the service will do.
3. The two delegation decisions from Phase 2 ("Will invoke `/integrate-webapi` for [tables]",
"Will invoke `ai-webapi-settings-architect` for Layer 3").
4. Existing-infrastructure notes (CSRF helper reuse, `powerPagesApi.ts`, previous
`aiSummaryService.*`).
### Approval cadence (set expectations up-front)
Before asking the integration question, briefly tell the user how many more decision points
are coming so the "one-shot" run isn't surprising. Count them from the
[Key decision points](#key-decision-points-wait-for-user) list, subtracting the ones that
don't apply for this run:
- **Search-only run**: drop the `/integrate-webapi` delegation (Phase 4) and the settings
architect (Phase 6) — 4–5 more pauses after this one.
- **Layer 1/2 already ready**: drop the Phase 4.3 architect approvals.
- **No list / scope-extends / intent-mismatch rows**: drop the per-target Phase 3 follow-ups.
- **First-time run with all branches firing**: 7–10 more pauses (web-role choice, per-target
list-trigger and scope-confirmation, two integrate-webapi architect plans, the AI
settings architect plan, two commit prompts, final deploy).
Phrase it as a heads-up, not a warning — e.g., "I'll pause for your input ~6 more times
after this one (web-role choice, two architect plans, two commit prompts, final deploy).
Could be a couple more if any list target needs a trigger or scope decision."
### The integration question
Use `AskUserQuestion` and **build the option list dynamically** from the Phase 2 manifest — do
not hardcode "Search summary and Data summarization" when only one category has candidates.
Construct the question text from what was found:
- If both categories have candidates: "I found candidates for Search Summary and Data
Summarization. Which should I integrate?"
- If only one category with one target: skip "All of them" — just confirm the single target
("Wire Search Summary into `<page>`?").
The default option list, with rows present only when the corresponding category has candidates:
| Option | When to include |
|--------|-----------------|
| All of them (Recommended) | Both categories present |
| Only Search Summary | Search candidates present AND Data Summarization candidates present |
| Only Data Summarization | Data Summarization candidates present AND Search candidates present |
| Let me select specific ones | Always (multi-target runs) |
| None — cancel | Always |
If the user chooses "Let me select specific ones", follow up with a multi-select question listing
each row of the integration manifest. When a detail-page candidate was flagged in Phase 2 as a
related-record-discovery target, include it as a dedicated option (in addition to any Data
Summarization option for the same page) so the user can consciously pick the AI-grounded path
rather than a hand-rolled OData match — e.g.:
- `Search Summary on CaseDetail.tsx (finds related KB articles via generative AI)`
- `Search Summary on ProductDetail.tsx (finds related products via generative AI)`
Label the option with the page name and the outcome it produces, not just "Search Summary", so the
user sees exactly where the AI surface will appear.
### Per-target follow-up questions
After the user confirms targets, ask per-target follow-up questions only when needed:
- **List-trigger** — every list target gets a "load on open" vs "manual button" question.
- **Scope confirmation** — only when Phase 2 flagged the row `scope-extends-beyond-existing-fetch`,
`needs-definition`, or `intent-mismatch`. Resolve `intent-mismatch` first because the
chosen target kind decides which scope question (LIST or SINGLE-RECORD) to ask next.
Question text, option lists, and the scope-classification → question mapping live in
`${PLUGIN_ROOT}/skills/add-ai-webapi/references/scope-classification.md`. Read it
when any per-target follow-up is required.
The chosen values flow into the Phase 5 agent-invocation prompt as the **Scope for the summary
call** block (`$filter`, `$orderby`, `Scope source`, `Target's existing list fetch`). The
existing UI fetch on the target component stays in place unchanged — the summary URL is an
addition, never a replacement.
If the user picks a scope that adds new `$expand` targets (e.g., "include its line items"),
re-evaluate the Phase 2 Layer 1/2 delegation decision — the new expansion is a new
prerequisite (Web API enabled + parent-scope permission on the child table).
### Handling "None — cancel"
When the user picks `None — cancel`:
1. Mark the remaining tasks as `completed` with a `(skipped — cancelled by user)` suffix in the
activeForm so the task list reads cleanly rather than leaving them stuck `pending`.
2. Jump straight to **Phase 8.1** (record skill usage with `--skillName "AddAiWebapi"` and an
outcome of `cancelled`) and **Phase 8.2** (present a one-line summary: "No changes made — you
cancelled at the plan-review step").
3. Skip Phases 4, 5, 6, 7, and 8.3 entirely. Do **not** invoke `/integrate-webapi`,
`ai-webapi-integration`, `ai-webapi-settings-architect`, or `/deploy-site`. Do **not** commit.
**Output**: user-confirmed integration manifest, or a clean cancellation.
---
## Phase 4: Delegate Layer 1 + Layer 2
**Goal**: Ensure every Web API prerequisite for the AI target tables exists, by delegating to
`/create-webroles` and `/integrate-webapi` (AI-only read mode) instead of writing Layer 1/2 files
directly.
### 4.1 Skip-check
Skip this entire phase when **any** of the following is true:
- Every confirmed target is Search Summary (search has no per-table Web API prerequisites).
- The Phase 2 delegation decision said "Run `/integrate-webapi`? No" — all Layer 1/2 prerequisites
are already on disk from prior runs.
- `.powerpages-site` does not exist (the sub-skills both require it).
In the skip case, proceed to Phase 5 and note this in the final summary.
### 4.2 Create missing web roles (if needed)
From Phase 1.6: if no web roles exist in `.powerpages-site/web-roles/`, or the roles that exist
don't match the site's auth model, ask the user:
| Question | Header | Options |
|----------|--------|---------|
| `/integrate-webapi` needs at least one web role to attach table permissions to. No matching role was found. Create one now via `/create-webroles`? | Web role | Yes, create via /create-webroles (Recommended), Skip — I'll handle roles separately |
On **Yes**: invoke the `Skill` tool for `power-pages:create-webroles` with a prompt that
includes the caller-suppress sentinel so the sub-skill does not issue its own deploy
prompts (the orchestrator owns the single end-of-run deploy decision):
> `[CALLED-BY-PARENT-SKILL] caller=add-ai-webapi`
>
> Create web roles for this Power Pages SPA site. The parent skill `/add-ai-webapi` will
> later attach AI-only read-mode table permissions to the role(s) you create. Do not issue
> deploy-now prompts — the orchestrator batches the deploy at the end.
Wait for it to complete. Then re-check `.powerpages-site/web-roles/` before proceeding to 4.3.
On **Skip**: this puts the run on a known-broken path — the AI endpoints will return 403 at
runtime until the user manually creates a web role + table permissions. Don't fall through
silently.
<!-- gate: add-ai-webapi:4.2.skip-webrole | category=consent | cancel-leaves=nothing -->
> 🚦 **Gate (consent · add-ai-webapi:4.2.skip-webrole):** Explicit acknowledgement before continuing without a web role — skipping leaves Layer 1/2 broken at runtime.
>
> **Trigger:** User chose "Skip" on the web-role creation offer.
> **Why we ask:** Proceeding silently means the AI API endpoints return 403 at runtime; surfacing the trade-off lets the user make an informed stop-vs-continue choice.
> **Cancel leaves:** Nothing — no code written yet.
Confirm the trade-off with a second `AskUserQuestion`:
| Question | Header | Options |
|----------|--------|---------|
| Without a web role I can't set up table permissions, so the AI endpoints will return 403 at runtime until you configure them yourself. Stop here so you can run `/create-webroles` first, or continue to write the frontend code anyway and let me flag the gap in the final summary? | Continue? | Stop here (Recommended), Continue — write frontend code only and flag the gap in the summary |
On **Stop here**: end the skill cleanly. Tell the user to run `/create-webroles` (and optionally
`/integrate-webapi`) first, then re-invoke `/add-ai-webapi`.
On **Continue**: skip the rest of Phase 4 (the `/integrate-webapi` delegation needs a web role to
attach permissions to, so running 4.3 would fail) and jump to Phase 5. In the Phase 8 summary,
flag the Layer 1/2 gap loudly — list the exact files the user still needs to create
(`Webapi/<table>/enabled`, `Webapi/<table>/fields`, table permissions per target) so the path to
a working runtime is obvious from the final message.
### 4.3 Invoke `/integrate-webapi` in AI-only read mode
Build the sentinel arguments from the Phase 2 manifest:
- `primary=<primary table logical name>` (the table whose record / collection is being summarised — e.g., `incident`, `cr4fc_product`, `cr363_workorder`)
- `tables=<primary plus every $expand target, comma-separated>`
- `expand-targets=<every $expand target, comma-separated; empty for pure data-summary targets with no $expand>`
- `caller=add-ai-webapi`
Invoke the `Skill` tool for `power-pages:integrate-webapi` with a single prompt:
> `[AI-READ-ONLY] mode=ai-read-only primary=<primary> tables=<list> expand-targets=<list> caller=add-ai-webapi`
>
> Configure Layer 1/2 (Web API site settings + table permissions) for the following Power Pages
> AI summarization targets: <table list>. This is a read-only integration — the `/_api/summarization/data/v1.0/`
> endpoint never mutates...
© Microsoft · MIT · microsoft/power-platform-skills