@se-studio/skills 1.0.35 → 1.0.36

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/skills
 
+## 1.0.36
+
+### Patch Changes
+
+- 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.36",
   "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-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)

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."
 ---
 

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

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