microsoft · poojalnu · Aug 26, 2026
@@ -149,6 +149,7 @@ User-invocable via `/power-pages:<skill-name>`:
 - `add-sample-data`: 6-step workflow — verify prerequisites, discover tables (from `.datamodel-manifest.json` or OData API), select tables & configure record count, generate & review sample data plan, insert records via OData API with relationship handling, verify & summarize.
 - `activate-site`: 5-step workflow — verify prerequisites (PAC CLI auth + Azure CLI token + cloud-aware API URL resolution + activation status check via shared script), gather parameters (site name, subdomain, website record ID), confirm with user, activate & poll via `skills/activate-site/scripts/activate-site.js`, present summary with site URL.
 - `add-seo`: 7-step workflow — verify site exists, gather SEO config (production URL, exclusions, meta description), plan & approve, create robots.txt, generate sitemap.xml from discovered routes, add meta tags (title, description, viewport, Open Graph, Twitter Card, favicon) to index.html, verify via Playwright & commit.
+- `perf-checker`: 6-phase (+1.5 Learn grounding) workflow — locate an existing local site folder (code-site markers or a classic PAC download with root-level `.portalconfig` / `website.yml`; an explicitly supplied folder does not require `powerpages.config.json` or `.powerpages-site/`), scan the entire local codebase via the deterministic `skills/perf-checker/scripts/analyze-perf.js` for performance anti-patterns (Power Pages lists without page size, FetchXML/entity-backed webpages used as JSON/XML APIs, FetchXML `all-attributes`/no-columns/many-columns/no-paging/large-count/N+1-in-loop/`returntotalrecordcount`/advanced query hints/cache bypassing/leading-wildcard filters/related-column ordering, Web API `$select=*`/no-`$select`/many-columns/no-`$top`/large-`$top`/`$count=true`/expanded rows without nested `$select`/contains-or-endswith filters/request-time date cache bypassing/related-column ordering/N+1, main-thread-blocking client JS — sync XHR, sync jQuery AJAX, `document.write`, short-interval `/_api/` polling — render-blocking `<head>` scripts, runtime CSS `@import`, header/footer output caching disabled, sign-in & page/file tracking, web-file/web-role counts, oversized assets), present findings by severity, offer safe auto-fixes for the site-setting/tracking findings with explicit per-fix consent (surfacing the `{% substitution %}` output-cache caveat), re-scan to verify, then render an HTML report via the shared `build-review-data.js` + `render-review.js` pipeline (`perf-checker.json` → Performance section) and route the manual list/webpage/FetchXML/Web API/JS/CSS fixes. Read-only until consent; supports `--review <out-dir>` mode, including using that directory as the project root when it contains site source. Validator: `skills/perf-checker/scripts/validate-perf-checker.js`. Rule catalog: `skills/perf-checker/references/perf-reference.md`.
 - `create-webroles`: 6-step workflow — verify `.powerpages-site/web-roles/` exists (redirect to deploy-site if missing), discover existing roles, determine new roles needed, create web role YAML files with UUIDs from shared `scripts/generate-uuid.js`, verify web roles (validate files, UUIDs, uniqueness constraints), review & prompt deployment via deploy-site skill.
 - `integrate-webapi`: 7-step workflow — verify site exists, use Explore agent to analyze code and identify tables needing Web API integration, review plan with user, invoke `webapi-integration` agent per table to create API client/types/services/hooks, verify integrations (validate all files exist, project builds), invoke `table-permissions-architect` and `webapi-settings-architect` agents (in parallel) to configure table permissions and site settings, review & deploy via `deploy-site` skill. Supports an `[AI-READ-ONLY]` sentinel that hardens the flow to read-only when invoked by `/add-ai-webapi`.
 - `add-ai-webapi`: 8-phase workflow — verify site/deployment, Explore-agent scan for search/data summarization candidates, review plan with user, **delegate Layer 1/2** (Web API site settings + table permissions) to `/integrate-webapi` in AI-only read mode and to `/create-webroles`, invoke `ai-webapi-integration` agent **sequentially per target** to create the summarization service + framework wrapper + UI wiring, invoke `ai-webapi-settings-architect` for Layer 3 (`Summarization/*` settings), verify (header-contract grep, `$select` grep, build, validator), review & deploy. This skill owns **Layer 3 only** and delegates everything else. Validator: `skills/add-ai-webapi/scripts/validate-ai-webapi.js`. AI summarization APIs are a **preview** feature gated by a three-level admin hierarchy.
@@ -266,7 +267,7 @@ Shared reference documents live at `references/` and are referenced by multiple
 - `solution-api-patterns.md`: OData body templates for publisher POST, solution POST, `AddSolutionComponent`, `ExportSolutionAsync`, `DownloadSolutionExportData`, `ImportSolutionAsync`, `StageSolution`. Also documents `.solution-manifest.json` format. Used by `setup-solution`, `export-solution`, and `import-solution`.
 - `deployment-error-catalog.md`: Catalog of 10 known deployment failure patterns (stale manifest, blocked JS, missing websiteRecordId, auth expiry, empty build output, solution missing dependencies, solution timeout, PAC CLI not installed, environment mismatch, duplicate component). Each entry includes root cause, severity, auto-fix availability, and fix procedure. Used by `diagnose-deployment`.
 - `cicd-pipeline-patterns.md`: PAC CLI service principal auth syntax; complete ADO `azure-pipelines.yml` template; complete GitHub Actions `deploy.yml` template; commented solution export/import blocks; secrets/variables setup tables; manual steps that cannot be automated; **Power Platform Pipelines API patterns** (HAR-confirmed): host env discovery via `RetrieveSetting`, `deploymentenvironments` create + `validationstatus` poll, `deploymentpipelines` create, `$ref` associate source (relative path format), `deploymentstages` create, `RetrieveDeploymentPipelineInfo`, stage run create + `ValidatePackageAsync` (204) + `operation` poll, `deploymentsettingsjson` PATCH, `DeployPackageAsync`, `stagerunstatus` terminal values, `docs/alm/last-pipeline.json` and `docs/alm/last-deploy.json` formats. Used by `setup-pipeline` and `deploy-pipeline`.
-- `approval-gates.md`: Canonical terminology, marker syntax, and catalog of every user-confirmation point ("Approval Gate") across the **entire power-pages skill set** (12 ALM + 12 non-ALM). Defines six categories (`intent` / `plan` / `progress` / `consent` / `final` / `pause`), an explicit-pairing marker (`<!-- gate: skill:phase | category=X | cancel-leaves=Y -->` + human `> 🚦 Gate (...)` block), the `cancel-leaves` vocabulary, and the seven gate-related lint rules enforced by `scripts/lint-skills-alm.js` at hard-fail severity: `GATE-must-have-marker`, `GATE-id-must-be-unique`, `GATE-must-be-in-catalog`, `GATE-intent-must-call-helper`, `GATE-cancel-leaves-known-vocab`, `GATE-prose-block-required` (marker must be followed by a 🚦 prose block within 10 lines, outside any code fence), and `CATALOG-row-must-have-marker` (reverse of `GATE-must-be-in-catalog` — every `kind: gate` catalog row must have a SKILL.md marker). §6.1–§6.12 catalogue the ALM skills; §6.13–§6.24 catalogue the non-ALM skills (`create-site`, `deploy-site`, `add-server-logic`, `add-cloud-flow`, `setup-auth`, `integrate-webapi`, `setup-datamodel`, `add-sample-data`, `add-seo`, `create-webroles`, `audit-permissions`, `integrate-backend`). `report-issue` is excluded because its workflow lives in the cross-plugin shared file. **New skills must extend §6 in the same PR they introduce an `AskUserQuestion`** — lint will block the PR otherwise.
+- `approval-gates.md`: Canonical terminology, marker syntax, and catalog of every user-confirmation point ("Approval Gate") across the **entire power-pages skill set** (12 ALM + 18 non-ALM). Defines six categories (`intent` / `plan` / `progress` / `consent` / `final` / `pause`), an explicit-pairing marker (`<!-- gate: skill:phase | category=X | cancel-leaves=Y -->` + human `> 🚦 Gate (...)` block), the `cancel-leaves` vocabulary, and the seven gate-related lint rules enforced by `scripts/lint-skills-alm.js` at hard-fail severity: `GATE-must-have-marker`, `GATE-id-must-be-unique`, `GATE-must-be-in-catalog`, `GATE-intent-must-call-helper`, `GATE-cancel-leaves-known-vocab`, `GATE-prose-block-required` (marker must be followed by a 🚦 prose block within 10 lines, outside any code fence), and `CATALOG-row-must-have-marker` (reverse of `GATE-must-be-in-catalog` — every `kind: gate` catalog row must have a SKILL.md marker). §6.1–§6.12 catalogue the ALM skills; §6.13–§6.30 catalogue the non-ALM skills (`create-site`, `deploy-site`, `add-server-logic`, `add-cloud-flow`, `setup-auth`, `integrate-webapi`, `setup-datamodel`, `add-sample-data`, `add-seo`, `create-webroles`, `audit-permissions`, `integrate-backend`, `manage-firewall`, `manage-headers`, `scan-site`, `security-review`, `add-ai-webapi`, `perf-checker`). `report-issue` is excluded because its workflow lives in the cross-plugin shared file. **New skills must extend §6 in the same PR they introduce an `AskUserQuestion`** — lint will block the PR otherwise.
 
 Skill-specific reference docs (e.g., `skills/setup-datamodel/references/odata-api-patterns.md`) contain only patterns unique to that skill and point to the shared docs via `${PLUGIN_ROOT}/references/` paths for common content.
 
@@ -292,6 +293,10 @@ Checks created Dataverse data models by reading `.datamodel-manifest.json` (writ
 
 Checks SEO assets added to Power Pages sites: verifies `robots.txt` exists in `public/` with proper `User-agent` and `Sitemap` directives, `sitemap.xml` exists with `<urlset>` and `<loc>` entries (no unreplaced placeholders), and `index.html` has `meta description` and `viewport` tags. Only runs validation when at least one SEO file (robots.txt or sitemap.xml) is detected — gracefully exits 0 otherwise to avoid blocking non-SEO sessions.
 
+### `perf-checker/scripts/validate-perf-checker.js`
+
+Checks that the performance report was generated. Globs `docs/` for a timestamped `perf-check-*.html` and, on the newest one, blocks only when the render clearly failed — the file is suspiciously small (< 500 bytes) or still contains unreplaced `__PLACEHOLDER__` tokens from the shared report template. Fail-open by design: gracefully exits 0 when the cwd is not a Power Pages project, when `docs/` has no perf report (prerequisites not met, or `--review` mode wrote JSON elsewhere), or when the report is well-formed — the hook fires on every `perf-checker` run, so a legitimate no-report exit must not block.
+
 ### `create-webroles/scripts/validate-webroles.js`
 
 Checks that web role YAML files were created in `.powerpages-site/web-roles/`. Validates each file has required `id` and `name` fields and that the `id` field contains a valid UUID v4 format. Gracefully exits 0 when no `.powerpages-site/web-roles/` directory is found (not a web roles session).

@@ -38,7 +38,7 @@ This keeps hook behavior in one place and avoids relying on skill-frontmatter ho
 
 ## Skills
 
-The plugin provides 30 skills that cover the full lifecycle of a Power Pages code site — scaffolding, deployment, data modeling, backend integration, authentication, ALM and CI/CD, security review, testing, and auditing. Each skill is invoked conversationally — just describe what you want to do.
+The plugin provides 31 skills that cover the full lifecycle of a Power Pages code site — scaffolding, deployment, data modeling, backend integration, authentication, ALM and CI/CD, security review, performance, testing, and auditing. Each skill is invoked conversationally — just describe what you want to do.
 
 ### Site scaffolding and deployment
 
@@ -377,6 +377,18 @@ Adds search engine optimization artifacts: `robots.txt`, `sitemap.xml`, and meta
 - Generates sitemap with production URLs
 - Adds viewport, charset, description, and social sharing meta tags
 
+#### `/perf-checker`
+
+> "Check my site for performance anti-patterns"
+
+Statically scans the entire local codebase for Power Pages performance anti-patterns — unpaginated lists, webpages/web templates used as APIs, FetchXML over-fetching, N+1 queries, wildcard/contains-style filters, advanced query hints, query cache bypassing, unbounded/over-expanded Web API calls, related-column ordering, disabled header/footer output caching, sign-in and page tracking, and oversized assets — then produces an HTML report by severity and offers safe auto-fixes with per-fix approval.
+
+- Grounded in the Site Checker performance checklist and FetchXML/Web API best practices
+- Supports code-site projects and classic PAC downloads with root-level `.portalconfig` / `website.yml` metadata
+- Reviews list pagination, webpage-as-API endpoints, FetchXML hints, and cache-busting patterns
+- Findings grouped by severity with concrete fixes and precise `file:line` locations
+- Auto-fixes site-setting/tracking issues on explicit per-finding consent; leaves code changes to you
+
 ### Support
 
 #### `/report-issue`