@se-studio/skills 1.0.35 → 1.0.37

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @se-studio/skills
 
+## 1.0.37
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.36
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+- 17d37e2: Fix skill descriptions not appearing in Claude Code selector (#30): standardize SKILL.md frontmatter (name matches directory, single-line quoted description, no extra YAML fields). Add `pnpm skills:validate`. Skill slash names now match directory names (e.g. `contentful-cms-core` instead of `contentful-cms:core`).
+
 ## 1.0.35
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,63 @@
+# @se-studio/skills
+
+Agent skills for SE Studio marketing site development with Contentful CMS.
+
+## Install
+
+**In this monorepo** — skills are synced into `.agents/skills/` (symlinked from `.cursor/skills/`):
+
+```bash
+pnpm skills:validate
+pnpm skills:sync
+```
+
+From this package directory: `pnpm validate` (runs the same frontmatter check).
+
+**In external projects:**
+
+```bash
+npx skills add @se-studio/skills
+```
+
+## Authoring skills
+
+Canonical sources live in `packages/skills/skills/<skill-dir>/SKILL.md`. Do **not** edit `.agents/skills/` by hand.
+
+### Frontmatter contract (Claude Code compatible)
+
+Every `SKILL.md` must start with YAML frontmatter containing **only** `name` and `description`:
+
+```yaml
+---
+name: se-marketing-sites-create-component
+description: "Guide for creating new CMS-driven components. Use when asked to create a new CMS component."
+---
+```
+
+Rules:
+
+| Field | Requirement |
+|-------|-------------|
+| `name` | Must exactly match the skill directory name; `[a-z0-9-]+` only; max 64 characters |
+| `description` | Single line, double-quoted, non-empty, max 1024 characters; no backticks |
+
+Do **not** use:
+
+- YAML block scalars for description (`>`, `|`)
+- Multiline descriptions
+- Extra frontmatter keys (`license`, `metadata`, `promptSignals`, etc.) — put those in the markdown body if needed
+- Invalid `name` values (spaces, capitals, colons, dots)
+
+Claude Code uses a naive frontmatter parser; violations cause descriptions to silently disappear from the skill selector.
+
+### Workflow
+
+1. Edit `packages/skills/skills/<skill-dir>/SKILL.md`
+2. Validate: `pnpm skills:validate`
+3. Sync: `pnpm skills:sync`
+4. Add a changeset if publishing `@se-studio/skills`
+
+## References
+
+- [Anthropic skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- Monorepo skill index: root `CLAUDE.md` and `docs/AI_QUICK_REFERENCE.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.0.35",
+  "version": "1.0.37",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",
@@ -21,5 +21,8 @@
   "homepage": "https://github.com/Something-Else-Studio/se-core-product#readme",
   "bugs": {
     "url": "https://github.com/Something-Else-Studio/se-core-product/issues"
+  },
+  "scripts": {
+    "validate": "node ../../scripts/validate-skills.mjs"
   }
 }

package/skills/contentful-cms-alt-text-audit/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "Alt Text Audit"
+name: contentful-cms-alt-text-audit
 description: "Audit and improve image alt text across site pages using cms-edit, with brand-aware terminology and accessibility best practices."
 ---
 

package/skills/contentful-cms-cms-guidelines/README.md

@@ -18,7 +18,7 @@ Guidelines are short markdown fragments — one per CMS type — that describe h
    pnpm --filter <appName> generate-showcase
    ```
    This writes `src/generated/showcase-examples.json`.
-3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md) to select the best examples into `showcase-mocks.json`. This makes the showcase (and screenshots) show realistic content.
+3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](../se-marketing-sites-curate-showcase-mocks/SKILL.md) to select the best examples into `showcase-mocks.json`. This makes the showcase (and screenshots) show realistic content.
 4. **Generate field list** — parse TypeScript types to produce structured field metadata:
    ```bash
    # From the app directory:
@@ -27,7 +27,7 @@ Guidelines are short markdown fragments — one per CMS type — that describe h
    # Or from repo root:
    pnpm --filter <appName> exec cms-generate-field-list --app-dir .
    ```
-5. **Generate guidelines** — run the [Generate CMS guidelines skill](.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md).
+5. **Generate guidelines** — run the [Generate CMS guidelines skill](../contentful-cms-generate-cms-guidelines/SKILL.md).
 
 Steps 1–3 only need to be repeated when content or component code changes significantly. Step 4 only needs to be repeated when TypeScript types change. Step 5 can be re-run at any time.
 
@@ -35,7 +35,7 @@ Steps 1–3 only need to be repeated when content or component code changes sign
 
 ## How to run guideline generation
 
-Use the Cursor skill at [`.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md`](.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md). It supports three modes:
+Use the Cursor skill at [`../contentful-cms-generate-cms-guidelines/SKILL.md`](../contentful-cms-generate-cms-guidelines/SKILL.md). It supports three modes:
 
 | Mode | When to use |
 |---|---|
@@ -43,25 +43,29 @@ Use the Cursor skill at [`.agents/skills/contentful-cms-generate-cms-guidelines/
 | `single` | Regenerate one component after code changes |
 | `merge-only` | Rebuild `COMPONENT_GUIDELINES_FOR_LLM.md` after manual fragment edits |
 
-**Example: full from scratch for `example-om1`**
+**Example: full from scratch**
 
 Start the app:
+
 ```bash
-pnpm --filter example-om1 dev
+pnpm dev
+# Note the port from dev server output, or read devBaseUrl from .contentful-cms.json
 ```
 
 Then invoke the skill with:
-- App directory: `apps/example-om1`
+
+- App directory: `<appDir>` (e.g. `.` in an external project)
 - Mode: `full`
-- Discovery URL: `http://localhost:3013/api/cms/discovery/`
+- Discovery URL: `http://localhost:<PORT>/api/cms/discovery/`
 
 **Example: single component**
 
 Invoke the skill with:
-- App directory: `apps/example-se2026`
+
+- App directory: `<appDir>`
 - Mode: `single`
 - Type name: `Hero`
-- Discovery URL: `http://localhost:3012/api/cms/discovery/`
+- Discovery URL: `http://localhost:<PORT>/api/cms/discovery/`
 
 **Example: merge only**
 
@@ -109,8 +113,8 @@ New project-independent CLI. Reads the discovery API and writes collection and e
 
 ```bash
 cms-generate-collection-guidelines \
-  --discovery-url http://localhost:3010/api/cms/discovery/ \
-  --app-dir apps/example-brightline
+  --discovery-url http://localhost:<PORT>/api/cms/discovery/ \
+  --app-dir <appDir>
 ```
 
 Options:

package/skills/contentful-cms-cms-guidelines/generation-prompt.md

@@ -115,7 +115,7 @@ Also provided:
 - The field list from generated/cms-discovery/field-list.json.
 - The project theme from generated/cms-discovery/theme-context.md (palette names + typography scale).
 - The screenshot index from docs/cms-guidelines/screenshots/index.json (lists captured screenshots).
-- The app's devBaseUrl from .contentful-cms.json (e.g. "http://localhost:3010").
+- The app's devBaseUrl from .contentful-cms.json (e.g. "http://localhost:<PORT>").
 
 Produce a single markdown fragment for <COMPONENT_TYPE> following EXACTLY this structure:
 

package/skills/contentful-cms-core/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "contentful-cms:core"
+name: contentful-cms-core
 description: "Use cms-edit CLI to read/edit Contentful content (open → snapshot → read → set/rtf → diff → save)."
 ---
 

package/skills/contentful-cms-generate-all-guidelines/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: generate-all-guidelines
-description: Full-site CMS guideline run — bulk screenshots (components + collections), CLI collection/externals, then Phase B/C/D for every component. After update-cms-guidelines fresh/clean slate, do not skip types or git-restore component fragments.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.1.0"
+name: contentful-cms-generate-all-guidelines
+description: "Full-site CMS guideline run — bulk screenshots (components + collections), CLI collection/externals, then Phase B/C/D for every component. After update-cms-guidelines fresh/clean slate, do not skip types or git-restore component fragments."
 ---
 
 # Generate All Guidelines (Full Site Run)
@@ -69,9 +65,9 @@ All of these must be true before starting. Check each one.
 
 | Input | Example |
 |-------|---------|
-| App directory (absolute or repo-relative) | `apps/example-se2026` or `/home/nick/source/se/se-website-2026` |
-| Discovery URL | `http://localhost:3012/api/cms/discovery/` |
-| Port | `3012` |
+| App directory (absolute or repo-relative) | `apps/my-site` or `/path/to/project` |
+| Discovery URL | `http://localhost:<PORT>/api/cms/discovery/` |
+| Port / base URL | From `pnpm dev` output, or `devBaseUrl` in `<appDir>/.contentful-cms.json` |
 
 ---
 
@@ -201,9 +197,9 @@ IMPORTANT: Screenshots have already been captured. Skip Phase A entirely.
 Go straight to Phase B.
 
 Files to read before starting:
-- packages/skills/skills/contentful-cms-cms-guidelines/generation-prompt.md  (Phase B instructions)
-- packages/skills/skills/contentful-cms-cms-guidelines/colour-hint-prompt.md  (Phase C instructions)
-- packages/skills/skills/contentful-cms-cms-guidelines/validation-prompt.md   (Phase D instructions)
+- ../contentful-cms-cms-guidelines/generation-prompt.md  (Phase B instructions)
+- ../contentful-cms-cms-guidelines/colour-hint-prompt.md  (Phase C instructions)
+- ../contentful-cms-cms-guidelines/validation-prompt.md   (Phase D instructions)
 - <APP_DIR>/src/project/components/<TypeName>.tsx  (component source)
 - <APP_DIR>/generated/cms-discovery/field-list.json
 - <APP_DIR>/src/generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json

package/skills/contentful-cms-generate-cms-guidelines/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "contentful-cms:generate-cms-guidelines"
+name: contentful-cms-generate-cms-guidelines
 description: "Generate, regenerate, or merge CMS guideline markdown fragments for any app in the monorepo."
 ---
 
@@ -32,7 +32,7 @@ Guidelines are only meaningful when the showcase is populated with realistic dat
    pnpm --filter <appName> generate-showcase
    ```
    This writes `src/generated/showcase-examples.json` to the app.
-3. **Curate showcase mocks:** Follow the [curate-showcase-mocks skill](.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md) to produce `showcase-mocks.json`.
+3. **Curate showcase mocks:** Follow the [curate-showcase-mocks skill](../se-marketing-sites-curate-showcase-mocks/SKILL.md) to produce `showcase-mocks.json`.
 4. **Generate field list:**
    ```bash
    # From the app directory:
@@ -51,17 +51,14 @@ Guidelines are only meaningful when the showcase is populated with realistic dat
 | **App directory** | Repo-relative path, e.g. `apps/example-om1` or `apps/example-se2026` |
 | **Mode** | `full` \| `single` \| `merge-only` |
 | **Type name** | Required for `single` mode — the exact type name from discovery, e.g. `"Hero"` or `"Cards Grid"` |
-| **Discovery URL** | URL to the live app's discovery endpoint, e.g. `http://localhost:3013/api/cms/discovery/` |
+| **Discovery URL** | `http://localhost:<PORT>/api/cms/discovery/` — `<PORT>` from the running dev server (`pnpm dev`) |
+| **Port / base URL** | Dev script output, or `devBaseUrl` in `<appDir>/.contentful-cms.json` |
 
-**App ports** (app must be running for `full` and `single` modes):
+The app must be running for `full` and `single` modes. Confirm with:
 
-| App | Port | Discovery URL |
-|---|---|---|
-| example-brightline | 3010 | `http://localhost:3010/api/cms/discovery/` |
-| example-se2026 | 3012 | `http://localhost:3012/api/cms/discovery/` |
-| example-om1 | 3013 | `http://localhost:3013/api/cms/discovery/` |
-| example-empty | 3014 | `http://localhost:3014/api/cms/discovery/` |
-| example-brightlifekids | 3015 | `http://localhost:3015/api/cms/discovery/` |
+```bash
+curl -sL http://localhost:<PORT>/api/cms/discovery/ | head -c 100
+```
 
 ---
 
@@ -115,7 +112,7 @@ Example of a completed `## Fields & Schema` section:
 ### Step 3 — Generate component guidelines
 
 For each component in discovery order, run the full per-component pipeline defined in
-[`packages/skills/skills/contentful-cms-cms-guidelines/generate-component-guidelines.md`](../../../packages/skills/skills/contentful-cms-cms-guidelines/generate-component-guidelines.md).
+[`generate-component-guidelines.md`](../contentful-cms-cms-guidelines/generate-component-guidelines.md).
 
 To find unfinished components:
 1. Fetch `<discoveryUrl>` and collect all `components[].name` values.
@@ -131,12 +128,12 @@ Run a Cursor subagent with this prompt, substituting `<COMPONENT_TYPE>` and `<AP
 Run the full guideline generation pipeline for <COMPONENT_TYPE>.
 Target app: <APP_DIR> (all paths relative to repo root / that directory).
 
-Read these pipeline docs first (they are in packages/skills/skills/contentful-cms-cms-guidelines/):
-- generate-component-guidelines.md  (overall pipeline)
-- variant-loop.md                   (Phase A: variant loop)
-- generation-prompt.md              (Phase B: generation)
-- colour-hint-prompt.md             (Phase C: colour hint)
-- validation-prompt.md              (Phase D: validation)
+Read these pipeline docs first (sibling directory contentful-cms-cms-guidelines/):
+- ../contentful-cms-cms-guidelines/generate-component-guidelines.md  (overall pipeline)
+- ../contentful-cms-cms-guidelines/variant-loop.md                   (Phase A: variant loop)
+- ../contentful-cms-cms-guidelines/generation-prompt.md              (Phase B: generation)
+- ../contentful-cms-cms-guidelines/colour-hint-prompt.md             (Phase C: colour hint)
+- ../contentful-cms-cms-guidelines/validation-prompt.md              (Phase D: validation)
 
 === Phase A: Variant loop ===
 Follow variant-loop.md.
@@ -271,8 +268,8 @@ Each component guideline contains a `## Screenshots` section with image links:
 
 | Variant | Preview |
 |---------|---------|
-| Default | ![Default](http://localhost:3010/cms/screenshot?file=components/hero-default.png) |
-| Navy    | ![Navy](http://localhost:3010/cms/screenshot?file=components/hero-navy.png) |
+| Default | ![Default](<devBaseUrl>/cms/screenshot?file=components/hero-default.png) |
+| Navy    | ![Navy](<devBaseUrl>/cms/screenshot?file=components/hero-navy.png) |
 ```
 
 These links:
@@ -285,7 +282,7 @@ These links:
 
 ## Pipeline reference
 
-All per-component pipeline docs live in `packages/skills/skills/contentful-cms-cms-guidelines/`:
+All per-component pipeline docs live in the sibling directory [`contentful-cms-cms-guidelines/`](../contentful-cms-cms-guidelines/):
 
 | File | Purpose |
 |---|---|

package/skills/contentful-cms-image-guide/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "Image Guide"
+name: contentful-cms-image-guide
 description: "Generate a comprehensive image guide (both Markdown and HTML) for a site's CMS image assets, with rich AI-generated visual descriptions and content relationship trees."
 ---
 

package/skills/contentful-cms-navigation/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "contentful-cms:navigation"
+name: contentful-cms-navigation
 description: "Create or edit navigation entries and nav items in Contentful via cms-edit."
 ---
 

package/skills/contentful-cms-rich-text/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "contentful-cms:rich-text"
+name: contentful-cms-rich-text
 description: "Edit rich-text fields and insert embedded entries/assets via cms-edit."
 ---
 

package/skills/contentful-cms-schema-org/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "Schema.org Generation"
+name: contentful-cms-schema-org
 description: "Generate Schema.org structured data as Mustache templates for site pages and upload via cms-edit."
 ---
 

package/skills/contentful-cms-screenshots/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "contentful-cms:screenshots"
+name: contentful-cms-screenshots
 description: "Capture screenshots of components, collections, pages or persons via cms-edit."
 ---
 

package/skills/contentful-cms-seo-descriptions/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "SEO Descriptions"
+name: contentful-cms-seo-descriptions
 description: "Generate or improve SEO meta descriptions for pages using cms-edit, targeting keywords with the brand voice."
 ---
 

package/skills/contentful-cms-setup/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "contentful-cms:setup"
+name: contentful-cms-setup
 description: "Guide a user through installing and configuring the cms-edit MCP server for Claude Desktop."
 ---
 

package/skills/contentful-cms-templates/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "contentful-cms:templates"
+name: contentful-cms-templates
 description: "Create or edit templates (preContent, postContent, menu, footer, colours) in Contentful via cms-edit."
 ---
 

package/skills/contentful-cms-update-cms-guidelines/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: update-cms-guidelines
-description: Primary CMS guideline orchestration. Use `fresh` only after a full clean slate and complete pipeline (showcase → screenshots → new component prose via Phase B/C/D — never git-restore fragments). Use `sync` for incremental changes but always delete stale types. If the user is vague, ask whether they want a full clean regeneration or incremental sync before acting.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.1.0"
+name: contentful-cms-update-cms-guidelines
+description: "Primary CMS guideline orchestration. Use fresh only after a full clean slate and complete pipeline (showcase → screenshots → new component prose via Phase B/C/D — never git-restore fragments). Use sync for incremental changes but always delete stale types. If the user is vague, ask whether they want a full clean regeneration or incremental sync before acting."
 ---
 
 # Update CMS Guidelines
@@ -49,21 +45,11 @@ If they insist on “everything” / “from scratch” / “totally regenerate
 
 | Input | Example |
 |---|---|
-| App directory (repo-relative or absolute) | `apps/example-se2026` |
-| Port | `3012` |
-| Discovery URL | `http://localhost:3012/api/cms/discovery/` |
+| App directory (repo-relative or absolute) | `apps/my-site` |
+| Discovery URL | `http://localhost:<PORT>/api/cms/discovery/` |
+| Port / base URL | From `pnpm dev` output, or `devBaseUrl` in `<appDir>/.contentful-cms.json` |
 | Mode | `fresh` \| `sync` \| `merge-only` |
 
-**App ports:**
-
-| App | Port |
-|---|---|
-| example-brightline | 3010 |
-| example-se2026 | 3012 |
-| example-om1 | 3013 |
-| example-empty | 3014 |
-| example-brightlifekids | 3015 |
-
 ---
 
 ## Mode: fresh
@@ -112,7 +98,7 @@ grep -E "CONTENTFUL_SPACE_ID|CONTENTFUL_ACCESS_TOKEN|OPENAI_API_KEY|ANTHROPIC_AP
 ### Step 2 — Curate showcase mocks
 
 Read and follow the **curate-showcase-mocks** skill:
-`.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md`
+[`../se-marketing-sites-curate-showcase-mocks/SKILL.md`](../se-marketing-sites-curate-showcase-mocks/SKILL.md)
 
 This produces `src/generated/showcase-mocks.json` (committed) and
 `src/generated/cms-discovery/accepted-variants/{components|collections|externals}/<slug>.json` (often gitignored — **some apps commit them**; follow the app’s `.gitignore`).
@@ -150,7 +136,7 @@ Produces `generated/cms-discovery/field-list.json` (discovery API reads from thi
 ### Step 5 — Run generate-all-guidelines
 
 Read and follow the **generate-all-guidelines** skill:
-`.agents/skills/contentful-cms-generate-all-guidelines/SKILL.md`
+[`../contentful-cms-generate-all-guidelines/SKILL.md`](../contentful-cms-generate-all-guidelines/SKILL.md)
 
 Skip its prerequisite check (you already verified everything through Step 4).
 Run Phases 0–5 from that skill with **full regeneration rules**:
@@ -342,7 +328,7 @@ All under `<appDir>`:
 
 | Purpose | Skill |
 |---|---|
-| Curate showcase mocks (Step 2 of `fresh`) | `.agents/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md` |
-| Full-site bulk generation (Step 4 of `fresh`: Phases 0–5) | `.agents/skills/contentful-cms-generate-all-guidelines/SKILL.md` |
-| Single-type regeneration (after code change) | `.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md` (mode: single) |
-| Per-component pipeline detail | `packages/skills/skills/contentful-cms-cms-guidelines/generate-component-guidelines.md` |
+| Curate showcase mocks (Step 2 of `fresh`) | [`../se-marketing-sites-curate-showcase-mocks/SKILL.md`](../se-marketing-sites-curate-showcase-mocks/SKILL.md) |
+| Full-site bulk generation (Step 4 of `fresh`: Phases 0–5) | [`../contentful-cms-generate-all-guidelines/SKILL.md`](../contentful-cms-generate-all-guidelines/SKILL.md) |
+| Single-type regeneration (after code change) | [`../contentful-cms-generate-cms-guidelines/SKILL.md`](../contentful-cms-generate-cms-guidelines/SKILL.md) (mode: single) |
+| Per-component pipeline detail | [`generate-component-guidelines.md`](../contentful-cms-cms-guidelines/generate-component-guidelines.md) |

package/skills/performance-audit/SKILL.md

@@ -1,57 +1,20 @@
 ---
 name: performance-audit
-description: >
-  Measure and improve Next.js app performance: bundle analysis, Lighthouse,
-  and real-user monitoring. Generic — works with any Next.js deployment on Vercel.
-metadata:
-  author: se-core-product
-  version: "1.0.0"
-  priority: 5
-  promptSignals:
-    phrases:
-      - performance
-      - lighthouse
-      - bundle size
-      - bundle analysis
-      - LCP
-      - core web vitals
-      - CWV
-      - speed insights
-      - page speed
-      - slow pages
-      - optimize performance
-      - analyse bundle
-      - analyze bundle
-      - web vitals
-retrieval:
-  aliases:
-    - perf
-    - web vitals
-    - bundle
-    - lighthouse audit
-    - performance measurement
-  intents:
-    - measure page performance
-    - analyze bundle sizes
-    - improve Lighthouse scores
-    - set up performance tooling
-    - investigate slow LCP
-    - add speed insights
-    - run bundle analyzer
-  entities:
-    - LCP
-    - CLS
-    - TBT
-    - TTFB
-    - FCP
-    - bundle analyzer
-    - Lighthouse
-    - Speed Insights
-    - Core Web Vitals
+description: "Measure and improve Next.js app performance: bundle analysis, Lighthouse, and real-user monitoring. Generic — works with any Next.js deployment on Vercel."
 ---
 
 # Next.js Performance Audit
 
+## Discovery hints
+
+Use this skill when the user mentions performance, Lighthouse, bundle size, LCP, Core Web Vitals, Speed Insights, or page speed optimization.
+
+**Aliases:** perf, web vitals, bundle, lighthouse audit, performance measurement
+
+**Common intents:** measure page performance, analyze bundle sizes, improve Lighthouse scores, set up performance tooling, investigate slow LCP, add speed insights, run bundle analyzer
+
+**Related entities:** LCP, CLS, TBT, TTFB, FCP, bundle analyzer, Lighthouse, Speed Insights, Core Web Vitals
+
 ## Overview — Three-layer measurement strategy
 
 Always use all three layers. Bundle size ≠ Lighthouse score ≠ real-user experience.

package/skills/se-marketing-sites-cms-routes-and-appshared/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: cms-routes-and-appshared
-description: Guide for the (cms-routes) route group and appShared pattern. Use when setting up or migrating CMS-driven routing, creating new route segments, or refactoring page structure.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.0.0"
+name: se-marketing-sites-cms-routes-and-appshared
+description: "Guide for the (cms-routes) route group and appShared pattern. Use when setting up or migrating CMS-driven routing, creating new route segments, or refactoring page structure."
 ---
 
 # CMS Routes and appShared Pattern

package/skills/se-marketing-sites-create-collection/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: create-cms-collection
-description: Guide for creating new CMS-driven collections (component containers) in the SE Core Product monorepo. Use this skill when asked to create a new collection or "grid" component.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.1.0"
+name: se-marketing-sites-create-collection
+description: "Guide for creating new CMS-driven collections (component containers) in the SE Core Product monorepo. Use this skill when asked to create a new collection or grid component."
 ---
 
 # Creating CMS Collections

package/skills/se-marketing-sites-create-component/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: create-cms-component
-description: Guide for creating new CMS-driven components in the SE Core Product monorepo. Use this skill when asked to create a new component, ensuring adherence to the 4-layer architecture.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.1.0"
+name: se-marketing-sites-create-component
+description: "Guide for creating new CMS-driven components in the SE Core Product monorepo. Use this skill when asked to create a new component, ensuring adherence to the 4-layer architecture."
 ---
 
 # Creating CMS Components

package/skills/se-marketing-sites-create-page/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: create-page-route
-description: Guide for creating new Next.js App Router pages and dynamic routes in the SE Core Product framework. Use when creating CMS-driven pages, adding route segments, or setting up routing.
-license: Private
-metadata:
-  author: se-core-product
-  version: "2.0.0"
+name: se-marketing-sites-create-page
+description: "Guide for creating new Next.js App Router pages and dynamic routes in the SE Core Product framework. Use when creating CMS-driven pages, adding route segments, or setting up routing."
 ---
 
 # Creating Pages and Routes

package/skills/se-marketing-sites-curate-showcase-mocks/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: curate-showcase-mocks
-description: Extracts real component/collection data from Contentful and curates the best examples into showcase-mocks.json, making the CMS showcase display realistic content instead of generic placeholder text.
-license: Private
-metadata:
-  author: se-core-product
-  version: "2.1.0"
+name: se-marketing-sites-curate-showcase-mocks
+description: "Extracts real component/collection data from Contentful and curates the best examples into showcase-mocks.json, making the CMS showcase display realistic content instead of generic placeholder text."
 ---
 
 # Curate Showcase Mocks

package/skills/se-marketing-sites-handling-media/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: handling-media
-description: Guide for using images, videos, and animations in marketing sites using the ResponsiveVisual and VisualComponent systems.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.0.0"
+name: se-marketing-sites-handling-media
+description: "Guide for using images, videos, and animations in marketing sites using the ResponsiveVisual and VisualComponent systems."
 ---
 
 # Handling Media

package/skills/se-marketing-sites-lib-cms-structure/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: lib-cms-structure
-description: Guide for the lib directory structure in SE Core Product CMS apps. Use when setting up lib/, migrating from contentful-config, or adding new CMS configuration.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.0.0"
+name: se-marketing-sites-lib-cms-structure
+description: "Guide for the lib directory structure in SE Core Product CMS apps. Use when setting up lib/, migrating from contentful-config, or adding new CMS configuration."
 ---
 
 # Lib Directory Structure
@@ -63,6 +59,14 @@ registrations.ts (*RegistrationsList arrays)
 
 Add new components/collections to the appropriate *RegistrationsList array in `registrations.ts`. The `cms.ts` imports those arrays, builds Records via `buildComponentRecord` / `buildCollectionRecord` / `buildExternalRecord` (which enforce that every CMS type has a registration), then builds the maps used by `cms-server.ts`.
 
+## cms-types.ts discriminators
+
+In `cms-types.ts`, projects declare typed unions for renderer lookup — base interfaces omit these fields:
+
+- `IComponent.componentType` (Contentful `componentType`)
+- `ICollection.collectionType` (Contentful `collectionType`)
+- `IExternalComponent.externalComponentType` (Contentful **`externalComponentType`** — not `externalType`, which is never populated at runtime)
+
 ## Circular Dependency: Do Not Import cms-server in Components/Collections
 
 Components and collections in the registration chain (imported by `registrations.ts`) must **not** import from `cms-server` directly. Doing so creates a circular dependency (cms-server → cms → registrations → components → cms-server) that causes TDZ errors during RSC serialization.

package/skills/se-marketing-sites-register-cms-features/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: register-cms-features
-description: Guide for registering new components, collections, and external integrations in the CMS configuration (src/lib/registrations.ts).
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.0.0"
+name: se-marketing-sites-register-cms-features
+description: "Guide for registering new components, collections, and external integrations in the CMS configuration (src/lib/registrations.ts)."
 ---
 
 # Registering CMS Features

package/skills/se-marketing-sites-styling-system/SKILL.md

@@ -1,10 +1,6 @@
 ---
-name: styling-system
-description: Reference guide for the marketing site styling system, including typography, colors, grids, and RTF classes.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.1.0"
+name: se-marketing-sites-styling-system
+description: "Reference guide for the marketing site styling system, including typography, colors, grids, and RTF classes."
 ---
 
 # Styling System

package/skills/site-workflows-apply-design-snapshot/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: site-workflows-apply-design-snapshot
-description: Reads design.md and applies the design tokens to the project — updating tailwind.config.json (colours + typography), handling custom fonts, and regenerating all downstream files via pnpm codegen. Run after /figma-design-snapshot to sync the codebase with the latest Figma changes.
-license: MIT
-metadata:
-  author: se-studio
-  version: "1.0.0"
+description: "Reads design.md and applies the design tokens to the project — updating tailwind.config.json (colours + typography), handling custom fonts, and regenerating all downstream files via pnpm codegen. Run after figma-design-snapshot to sync the codebase with the latest Figma changes."
 ---
 
 # Apply Design Snapshot

package/skills/site-workflows-brand-context-builder/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "Brand Context Builder"
+name: site-workflows-brand-context-builder
 description: "Interactively create or update a brand context skill for a customer's site by analysing their content and asking refinement questions."
 ---
 

package/skills/site-workflows-contentful-vercel-setup/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: site-workflows-contentful-vercel-setup
-description: Set up Contentful revalidation webhooks and live preview for a new SE Studio project on Vercel. Creates the Contentful webhook via the Management API and sets REVALIDATION_SECRET in Vercel. Run after site-workflows-new-project bootstrap when the Vercel project is deployed.
-license: MIT
-metadata:
-  author: se-studio
-  version: "1.0.0"
+description: "Set up Contentful revalidation webhooks and live preview for a new SE Studio project on Vercel. Creates the Contentful webhook via the Management API and sets REVALIDATION_SECRET in Vercel. Run after site-workflows-new-project bootstrap when the Vercel project is deployed."
 ---
 
 # Contentful & Vercel Webhook Setup

package/skills/site-workflows-copy-doc-snapshot/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: site-workflows-copy-doc-snapshot
-description: Syncs content/copy/*.md files from the Google Docs copy document. Run whenever the copy doc is updated to pull changes into git. Produces a diff-friendly merge — CMS annotations and sync-to-CMS state are never touched.
-license: MIT
-metadata:
-  author: se-studio
-  version: "1.0.0"
+description: "Syncs content/copy/*.md files from the Google Docs copy document. Run whenever the copy doc is updated to pull changes into git. Produces a diff-friendly merge — CMS annotations and sync-to-CMS state are never touched."
 ---
 
 # Copy Doc Snapshot

package/skills/site-workflows-figma-design-snapshot/SKILL.md

@@ -1,9 +1,6 @@
 ---
-name: "Figma Design Snapshot"
+name: site-workflows-figma-design-snapshot
 description: "Regenerates design.md from Figma by extracting all design tokens, typography, and component specs. Produces a deterministic, git-diffable output — run on any day to see what designers have changed."
-metadata:
-  author: se-studio
-  version: "1.0.0"
 ---
 
 # Figma Design Snapshot

package/skills/site-workflows-new-project/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: site-workflows-new-project
-description: Bootstrap a new SE Studio customer project from the SE Studio template. Runs full project cleanup (black/white colors, system font, minimal registrations), then sets up CLAUDE.md, AGENTS.md, README files, STYLING.md, ANIMATION.md, and updates project identity (site title, description, .cursorrules). Use this immediately after cloning the template for a new client.
-license: MIT
-metadata:
-  author: se-studio
-  version: "1.0.0"
+description: "Bootstrap a new SE Studio customer project from the SE Studio template. Runs full project cleanup (black/white colors, system font, minimal registrations), then sets up CLAUDE.md, AGENTS.md, README files, STYLING.md, ANIMATION.md, and updates project identity (site title, description, .cursorrules). Use this immediately after cloning the template for a new client."
 ---
 
 # SE New Project Bootstrap

package/skills/site-workflows-project-cleanup/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: site-workflows-project-cleanup
-description: Strip an existing SE Studio Next.js/Contentful project to a bare-bones baseline — black/white color system, system font, only Generic Component, Generic Collection, and Related Articles Collection registered, with minimal navigation and footer stubs. Run this when you need to clean a customer project down to a reusable template.
-license: MIT
-metadata:
-  author: se-studio
-  version: "1.0.0"
+description: "Strip an existing SE Studio Next.js/Contentful project to a bare-bones baseline — black/white color system, system font, only Generic Component, Generic Collection, and Related Articles Collection registered, with minimal navigation and footer stubs. Run this when you need to clean a customer project down to a reusable template."
 ---
 
 # SE Project Cleanup