docs: add README for experience-ui-bundle-performance-optimize

Human-facing overview alongside SKILL.md, matching the convention used
by platform-soql-query and other single-purpose skills: features,
quick start, the before/after numbers from the reference sample, and
related-skills links.

skills/experience-ui-bundle-performance-optimize/README.md

@@ -0,0 +1,68 @@
+# experience-ui-bundle-performance-optimize
+
+Frontend performance auditing and optimization skill for Salesforce React UI Bundles. Measures Vite build output against size budgets, then applies route-level code splitting and vendor chunking to cut first-load JavaScript — without touching data layer, routing structure, or visual design.
+
+## Features
+
+- **Bundle Measurement**: Reads Vite's build report (or runs the bundled analyzer) against explicit size budgets for entry chunks, individual chunks, route chunks, and CSS
+- **Route-Level Code Splitting**: Converts eager page imports in `routes.tsx` to `React.lazy`, so each page ships its own chunk fetched on first navigation
+- **Vendor Chunking**: Configures `manualChunks` in `vite.config.ts` to separate rarely-changing dependencies (React, router, UI primitives, charts) into their own cacheable chunks
+- **Render-Waste Diagnosis**: Guidance for `memo`/`useMemo`/debouncing/virtualization — applied only against a reported symptom, not speculatively
+- **Verification Workflow**: Rebuild, re-measure, and click through every navigation entry to confirm lazy chunks load correctly
+
+## Quick Start
+
+### 1. Invoke the skill
+
+```
+Skill: experience-ui-bundle-performance-optimize
+Request: "This UI bundle's build is throwing a chunk-size warning, can you fix it?"
+```
+
+The skill also self-activates when a build prints Vite's `"Some chunks are larger than 500 kB"` warning, or when the user mentions slow load, bundle size, code splitting, or Core Web Vitals for a project under `uiBundles/*/src/`.
+
+### 2. Run the analyzer directly
+
+```bash
+node skills/experience-ui-bundle-performance-optimize/scripts/analyze-bundle.mjs <app-dir>/dist
+```
+
+Add `--json` for machine-readable output. Exits `0` when every budget passes, `1` when any budget is exceeded (suitable for CI gating), `2` on usage/IO errors.
+
+### 3. Typical use cases
+
+- Diagnose why a UI bundle's `npm run build` prints a chunk-size warning
+- Reduce first-load JavaScript before deploying a UI bundle to an org
+- Add code splitting to a UI bundle app that has grown past its initial page set
+- Investigate reported UI sluggishness (typing lag, slow list scroll, tab-switch delay)
+
+## Results on the Reference Sample
+
+Applied to `samples/ui-bundle-template-app-react-sample-b2e` (Property Management app):
+
+| | Before | After |
+|---|---|---|
+| Entry chunk | 1,104.74 kB (326.44 kB gzip) | 50.21 kB (16.28 kB gzip) |
+| Route chunks | none — all pages eager | 4 chunks, 9–16 kB each, loaded on navigation |
+| Vendor chunks | none | `react`, `router`, `radix`, `charts` — cacheable across deploys |
+| Vite size warning | yes | no |
+
+Verified at runtime: the home route renders correctly, and navigating to each page fetches exactly that page's lazy chunk (confirmed via network trace), nothing more.
+
+## Documentation
+
+- [SKILL.md](SKILL.md) — full workflow: measure → split routes → split vendors → fix render waste → verify, with size budgets and template-specific rules
+- [scripts/analyze-bundle.mjs](scripts/analyze-bundle.mjs) — standalone budget checker for `dist/` output
+
+## Boundaries
+
+- Does not touch the GraphQL data layer, router library, or component library — that is a rewrite, not an optimization
+- Does not enable production sourcemaps to "measure" — uses the build report or the analyzer instead
+- Does not change `outDir`, `assetsDir`, or `base` in `vite.config.ts` — those are relied on by deployment
+
+## Related Skills
+
+- `experience-ui-bundle-frontend-generate` — for visual/styling changes to an existing UI bundle app
+- `experience-ui-bundle-app-coordinate` — for building a new UI bundle app from scratch
+- `experience-ui-bundle-deploy` — for deploying the optimized bundle to a Salesforce org
+- `experience-ui-bundle-salesforce-data-access` — for GraphQL/data-layer concerns (org latency, query shape) that this skill does not address