@wix/agent-skills 1.6.0 → 1.7.0

package/skills/wix-headless/references/verticals/_schema.json

@@ -1,160 +1,74 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "Wix Headless Vertical Frontmatter",
-  "description": "Validates verticals/<name>.md frontmatter. Runs at session start; malformed vertical aborts the skill.",
+  "title": "Wix Headless Vertical Frontmatter (Phase 1 — discovery only)",
+  "description": "Validates verticals/<name>.md frontmatter. Phase 1 scope only — later phases (setup, seed, design, pages, build) are owned by @skills/wix-manage plus this skill's own templates and INSTRUCTIONS.md files; per-pack fields (packages, cmsCollections, seed, components, componentsCss, pages, creates, contributes, include) are not part of this skill and not validated here.",
   "type": "object",
-  "required": ["name", "description", "packages"],
-  "additionalProperties": true,
+  "required": ["name", "description"],
+  "additionalProperties": false,
   "properties": {
     "name": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
       "description": "Must match filename stem (e.g., stores.md → 'stores')"
     },
+    "description": { "type": "string" },
     "triggers": {
       "type": "array",
-      "items": { "type": "string" }
+      "items": { "type": "string" },
+      "description": "Prompt patterns that route to this vertical. Empty allowed for transitive-only packs (ecom, gift-cards, cms). The SKILL.md routing table is the actual source of truth for what gets loaded; this is human reference + a fallback signal."
     },
-    "description": { "type": "string" },
     "requires": {
       "type": "array",
-      "items": { "type": "string" }
+      "items": { "type": "string" },
+      "description": "Verticals that must be co-loaded in the same read batch when this pack is loaded. Today: stores → [ecom, gift-cards]; gift-cards → [ecom]."
     },
     "features": {
       "type": "array",
       "items": {
         "type": "object",
         "required": ["name", "description"],
+        "additionalProperties": false,
         "properties": {
           "name": { "type": "string" },
           "description": { "type": "string" }
         }
-      }
+      },
+      "description": "Feature blurbs for DISCOVERY.md Step 3 Section B."
     },
     "apps": {
-      "type": "array",
-      "items": {
-        "oneOf": [
-          { "type": "string", "description": "App name (resolved via known-apps.json)" },
-          {
-            "type": "object",
-            "required": ["name"],
-            "properties": {
-              "name": { "type": "string" },
-              "appDefId": { "type": "string" }
-            }
-          }
-        ]
-      }
-    },
-    "packages": {
-      "type": "array",
-      "minItems": 1,
-      "items": { "type": "string" }
-    },
-    "routes": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["route"],
+        "required": ["name"],
+        "additionalProperties": false,
         "properties": {
-          "route": { "type": "string", "description": "URL path (e.g. /cart) OR the literal 'Hosted by Wix' for Wix-hosted endpoints like checkout." },
-          "name": { "type": "string", "description": "Optional user-facing page name override for DISCOVERY.md's Section C table. When omitted, the orchestrator derives the name from the path (/ → Home; /thank-you → Thank You). Set this only when path-derivation produces a poor name (e.g. /products/[slug] → 'Product Detail') or when the route has no path (e.g. ecom's Wix-hosted Checkout)." }
-        }
-      }
-    },
-    "cmsCollections": { "type": "array" },
-    "seed": {
-      "oneOf": [
-        { "type": "null" },
-        {
-          "type": "object",
-          "required": ["agentLocation", "scope", "references"],
-          "properties": {
-            "agentLocation": { "type": "string" },
-            "scope": { "type": "string", "const": "seed" },
-            "description": { "type": "string" },
-            "references": { "type": "array", "items": { "type": "string" } }
-          }
-        }
-      ]
-    },
-    "components": {
-      "oneOf": [
-        { "type": "null" },
-        {
-          "type": "object",
-          "required": ["agentLocation", "scope", "references"],
-          "properties": {
-            "agentLocation": { "type": "string" },
-            "scope": { "type": "string", "const": "components" },
-            "description": { "type": "string" },
-            "references": { "type": "array", "items": { "type": "string" } },
-            "files": { "type": "array", "items": { "type": "string" } }
-          }
-        }
-      ]
-    },
-    "componentsCss": {
-      "oneOf": [
-        { "type": "null" },
-        {
-          "type": "object",
-          "required": ["agentLocation", "scope", "references"],
-          "description": "Optional sibling of `components`. When present, the orchestrator dispatches a second concurrent Phase 3 subagent that owns the pack's scoped CSS file only — independent of TSX/Astro work in the `components` scope. Used by packs whose `components` agent dominated phase wall time (today: stores). Backward compatible — packs without this field keep the single-agent shape.",
-          "properties": {
-            "agentLocation": { "type": "string" },
-            "scope": { "type": "string", "const": "components-css" },
-            "description": { "type": "string" },
-            "references": { "type": "array", "items": { "type": "string" } },
-            "files": { "type": "array", "items": { "type": "string" } }
-          }
+          "name": { "type": "string" },
+          "appDefId": { "type": "string" }
         }
-      ]
+      },
+      "description": "Zero or one entry per pack. apps[0].name fills the Source column of the Pages table."
     },
-    "pages": {
+    "routes": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["agentLocation", "scope", "references"],
+        "required": ["route"],
+        "additionalProperties": false,
         "properties": {
-          "name": { "type": "string" },
-          "agentLocation": { "type": "string" },
-          "scope": {
+          "route": {
             "type": "string",
-            "pattern": "^pages(-[a-z][a-z0-9-]*)?$",
-            "description": "Must be 'pages' or 'pages-<subscope>'"
+            "description": "URL path (e.g. /cart) OR the literal 'Hosted by Wix' for Wix-hosted endpoints like checkout."
           },
-          "description": { "type": "string" },
-          "references": { "type": "array", "items": { "type": "string" } },
-          "files": { "type": "array", "items": { "type": "string" } }
-        }
-      }
-    },
-    "creates": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["file", "phase"],
-        "properties": {
-          "file": { "type": "string" },
-          "phase": { "type": "string", "enum": ["seed", "components", "pages"] }
-        }
-      }
-    },
-    "contributes": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["file", "marker"],
-        "properties": {
-          "file": { "type": "string" },
-          "marker": { "type": "string", "pattern": "^<!--\\s.*\\s-->$" },
-          "description": { "type": "string" }
+          "name": {
+            "type": "string",
+            "description": "Optional user-facing page name override for DISCOVERY.md's Section C table. When omitted, the orchestrator derives the name from the path (/ → Home; /thank-you → Thank You). Set this only when path-derivation produces a poor name (e.g. /products/[slug] → 'Product Detail') or when the route has no path (e.g. ecom's Wix-hosted Checkout)."
+          }
         }
       }
     },
-    "include": { "type": "boolean", "description": "Pack-level loading flag. If true, the pack is loaded in every site regardless of triggers/requires (today: only the cms pack uses include:true). Default false — the pack loads only when triggers match the user's prompt or another pack pulls it in via requires." },
-    "disabled": { "type": "boolean", "description": "Pack-level activation flag, ORTHOGONAL to `include`. If true, the pack's surfaces (pages, nav links, home blocks) are disabled by default — they ship as code but do not appear without a separate user action (today: enabling the matching Wix app from the dashboard, which the pack's runtime probe detects). Files still ship via creates: / contributes: so activation is instant once the user opts in. DISCOVERY.md plan composition (Sections B + C) skips features and routes from disabled packs so the plan never promises a surface the user did not ask for. Today only the gift-cards pack uses disabled:true." }
+    "disabled": {
+      "type": "boolean",
+      "description": "If true, the pack's surfaces (pages, nav links, home blocks) are inactive by default — they ship as code but do not appear without a separate user action (today: enabling the matching Wix app from the dashboard, which the pack's runtime probe detects). DISCOVERY.md plan composition (Sections B + C) skips features and routes from disabled packs so the plan never promises a surface the user did not ask for. Today only the gift-cards pack uses disabled: true."
+    }
   }
 }

package/skills/wix-headless/references/verticals/_schema.md

@@ -1,10 +1,15 @@
-# Vertical Schema
+# Vertical Schema (Phase 1 — discovery only)
 
-Each file in `references/verticals/` declares one vertical's contribution to the build flow. The skill reads the user's prompt, loads matching verticals, and assembles the phase-based flow from them.
+Each file in `references/verticals/` declares one vertical's contribution to discovery. The skill reads the user's prompt, loads the matching pack set (per SKILL.md routing table), and assembles the plan from the loaded packs' frontmatter.
+
+> **Phase 1 scope.** This schema covers only what discovery needs. Later phases (setup, seed, design system, pages, build) are owned by an upstream skill plus this skill's own templates and `INSTRUCTIONS.md` files:
+> - `@skills/wix-manage` — REST API recipes for site setup and content seeding.
+>
+> Per-pack fields (`packages`, `cmsCollections`, `seed`, `components`, `componentsCss`, `pages`, `creates`, `contributes`, `include`) are not part of this schema — those concerns belong to upstream recipes and per-vertical templates, not this skill's vertical packs.
 
 ## File format
 
-Markdown with YAML frontmatter. The frontmatter is the machine-readable config. The markdown body is human-readable docs (what the vertical does, gotchas, examples).
+Markdown with YAML frontmatter. The frontmatter is the machine-readable config; the body is a short human-readable note about what the pack does and where its Phase 2+ implementation lives.
 
 ## Frontmatter fields
 
@@ -12,118 +17,43 @@ Markdown with YAML frontmatter. The frontmatter is the machine-readable config.
 ---
 # --- Identity ---
 name: stores                          # unique vertical name, matches the filename stem
+description: "Short one-liner — what the pack provides at a glance."
 triggers:                             # prompt patterns that route the user to this vertical
-  - "sell"
-  - "ecommerce"
-  - "store"
-  - "shop"
-description: "Full ecommerce: products, cart, checkout, thank-you"
+  - "sell"                            # case-insensitive substrings
+  - "ecommerce"                       # SKILL.md routing table is the source of truth for actual loading;
+                                      # this list is human reference + a fallback signal.
 
 # --- Dependencies ---
-requires: []                          # optional list of vertical names that must be co-loaded
-                                      # e.g. stores requires ["ecom"] for cart/checkout
+requires: []                          # optional — verticals that must be co-loaded.
+                                      # Example: stores requires ["ecom", "gift-cards"]; gift-cards requires ["ecom"].
+                                      # If a pack with `requires:` is loaded, every name in the list MUST be in the same read batch.
 
 # --- Plan contribution ---
-features:                             # human-readable feature blurbs for the plan
+features:                             # human-readable feature blurbs. Used in DISCOVERY.md Step 3 Section B.
   - name: "Product catalog"
     description: "Browse products with images, prices, and variants."
-  - name: "Cart & checkout"
-    description: "Add to cart, review, check out via Wix's hosted checkout."
 
-# --- Infrastructure ---
-apps:                                 # MCP app installs (0 or more per pack)
-  - name: "Wix Stores"
+# --- Plan Pages table ---
+apps:                                 # zero or one entry per pack. apps[0].name fills the Source column
+  - name: "Wix Stores"                # of DISCOVERY.md Step 3 Section C.
     appDefId: "215238eb-22a5-4c36-9e7b-e7c08025e04e"
-packages:                             # npm packages to install
-  - "@wix/stores"
-  - "@wix/ecom"
-  - "@wix/redirects"
-  - "@wix/site"
-
-# --- Routes this vertical contributes (for plan assembly) ---
-# Agent dispatch for rewriting page files lives under the 'pages:' phase entry further down.
-routes:
-  - route: "/products"
+
+routes:                               # routes the pack ships. Each entry → one row in the Pages table.
+  - route: "/products"                # `route:` value renders verbatim in the Route cell.
   - route: "/products/[slug]"
-    name: "Product Detail"                     # OPTIONAL: user-facing name override for DISCOVERY's Section C table. When omitted, the orchestrator derives the name from the path (/ → "Home"; /thank-you → "Thank You"). Override only when path-derivation produces a poor name (e.g. /products/[slug] would derive to "Products [slug]") OR when the route has no path (ecom's Wix-hosted Checkout uses route: "Hosted by Wix" + name: "Checkout").
-
-# --- CMS collections this vertical declares (if any) ---
-cmsCollections: []                    # stores adds none; the cms vertical adds About + FAQ
-
-# --- Seed phase: data seeding (MCP-only, no design-token dependency) ---
-seed:
-  agentLocation: "references/stores/"
-  scope: "seed"
-  description: "Delete default sample products, create on-brand products"
-  references: ["references/stores/PRODUCT_CATALOG_DATA.md"]
-
-# --- Components phase: shared React/Astro components (runs after Design System, parallel with other verticals' components) ---
-components:
-  agentLocation: "references/stores/"
-  scope: "components"
-  description: "SDK-wiring code and reusable islands (reads design tokens + site.d.ts)"
-  references: ["references/stores/SHARED_WIRING.md"]
-  files:
-    - "src/utils/wix-image.ts"
-    - "src/utils/analytics.ts"
-    - "src/components/SeoTags.astro"
-    - "src/components/AddToCartButton.tsx"
-    - "src/components/CartBadge.tsx"
-    - "src/components/ProductPurchase.tsx"
-    - "src/components/CartView.tsx"
-
-# --- Pages phase: route files (written ONCE with both visual design and data queries) ---
-pages:
-  - name: "product-pages"
-    agentLocation: "references/stores/"
-    scope: "pages-products"
-    references: ["references/stores/PRODUCT_PAGES.md"]
-    files:
-      - "src/pages/products/index.astro"
-      - "src/pages/products/[slug].astro"
-      - "src/components/ProductCard.astro"
-  - name: "cart-checkout"
-    agentLocation: "references/stores/"
-    scope: "pages-cart-checkout"
-    references: ["references/ecom/CART_PAGES.md"]
-    files:
-      - "src/pages/cart.astro"
-      - "src/pages/thank-you.astro"
-  - name: "home-and-nav"
-    agentLocation: "references/stores/"
-    scope: "pages-home-and-nav"
-    references: ["references/stores/HOME_AND_NAV.md"]
-    files:
-      - "src/pages/index.astro (patch)"
-      - "src/components/Navigation.astro (patch)"
-
-# --- File ownership declarations ---
-# `creates:` lists files this vertical is the sole author of. Schema validator
-#   enforces single-owner (two verticals claiming the same file → fail at session start)
-#   and unresolved-import check (if ANY loaded reference imports ../utils/X, some
-#   vertical must declare it in `creates:` OR it must be a plugin shared utility).
-# `contributes:` lists files this vertical co-edits via named markers. The Design
-#   System phase scaffolds shell files (Navigation.astro, index.astro) with markers;
-#   each vertical inserts at its marker. Replaces the old `homeSection:` concept —
-#   contributes[].description is surfaced in the plan shown to the user.
-# Skill-level shared utilities (wix-image.ts, analytics.ts, ricos.ts) are NEVER listed here —
-#   they ship via <SKILL_ROOT>/shared-utilities/ and are copied into projects by
-#   <SKILL_ROOT>/scripts/seed-utilities.sh during Setup.
-creates:
-  - { file: src/components/AddToCartButton.tsx, phase: components }
-  - { file: src/pages/products/index.astro,     phase: pages }
-
-contributes:
-  - file: src/pages/index.astro
-    marker: "<!-- home:stores -->"
-    description: "Featured products grid (3–6 items from productsV3.queryProducts)"
-  - file: src/components/Navigation.astro
-    marker: "<!-- nav:links -->"
-    description: "Shop menu link → /products"
-
-# --- Loading + activation (orthogonal pack-level flags) ---
-include: false                        # if true, the pack loads in every site regardless of triggers/requires (today: only `cms` sets include:true). Default false → loads on trigger match or via another pack's requires.
-disabled: false                       # if true, the pack ships its code but its surfaces (pages, nav, home blocks) are inactive by default — they light up only when the user takes a separate action (today: enabling the matching Wix app from the dashboard, detected by a runtime probe). DISCOVERY.md plan composition (Sections B + C) skips features and routes from disabled packs so the plan never promises a surface the user did not ask for. Today only `gift-cards` sets disabled:true. Default false.
+    name: "Product Detail"            # OPTIONAL: user-facing name override for the Page cell. When omitted,
+                                      # the orchestrator derives the name from the path (/ → "Home";
+                                      # /thank-you → "Thank You"). Override only when path-derivation
+                                      # produces a poor name (e.g. "/products/[slug]" → "Products [slug]")
+                                      # OR when the route has no path (use the literal string "Hosted by Wix").
+
+# --- Activation ---
+disabled: false                       # if true, the pack ships its code but its surfaces (pages, nav, home blocks) are inactive
+                                      # by default — they light up only when the user takes a separate action (today: enabling
+                                      # the matching Wix app from the dashboard, detected by a runtime probe). DISCOVERY.md plan
+                                      # composition (Sections B + C) skips features and routes from disabled packs so the plan
+                                      # never promises a surface the user did not opt into. Today only `gift-cards` sets
+                                      # `disabled: true`. Default false.
 ---
 ```
 
@@ -131,55 +61,35 @@ disabled: false                       # if true, the pack ships its code but its
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
-| `name` | string | yes | Matches filename stem (e.g., `stores.md` → `name: stores`) |
-| `triggers` | string[] | yes unless `include: true` | Case-insensitive substrings matched against user prompt |
-| `description` | string | yes | Short label for the plan |
-| `features` | object[] | yes | Feature blurbs for the plan's "Features" section |
-| `apps` | object[] | no | MCP app installs; `{name, appDefId}` pairs |
-| `packages` | string[] | yes | npm packages |
-| `routes` | object[] | no | `{route, name?}` — routes the pack ships. Optional `name` overrides the path-derived page name in DISCOVERY's Section C. |
-| `cmsCollections` | object[] | no | Collections this vertical adds |
-| `seed` | object | no | Seed-phase agent config; omit if the vertical has no seeding |
-| `components` | object | no | Components-phase agent config; omit if none |
-| `pages` | object[] | no | Pages-phase agent dispatch (one entry per page-rewrite sub-scope) |
-| `creates` | object[] | no | `{file, phase}` — files this vertical is sole author of. Schema validator enforces single-owner + unresolved-import check. |
-| `contributes` | object[] | no | `{file, marker, description}` — files this vertical co-edits via named markers. |
-| `include` | bool | no | If true, the pack loads in every site regardless of triggers/requires (today: only `cms`). Controls **loading**. |
-| `disabled` | bool | no | If true, the pack ships its code but its surfaces are inactive by default — they light up only via a separate user action (today: enabling the matching Wix app from the dashboard; the pack's runtime probe detects it). DISCOVERY plan composition skips disabled packs from Sections B + C. Today only `gift-cards`. Controls **activation**. |
-
-### `include` vs `disabled` — orthogonal axes
-
-The two flags answer different questions. Don't conflate them:
-
-- **`include`** — *Is this pack in the loaded set?* Default: load when triggers match or another pack pulls it in via `requires:`. `include: true` overrides that and forces the pack to load in every site. Used by `cms` (every site needs About/FAQ).
-- **`disabled`** — *Do this pack's surfaces appear without further user action?* Default: yes — the moment the pack is loaded, its routes and contributions are live. `disabled: true` says no — the code ships, but a separate runtime check (today: a dashboard-app probe) decides whether to render. Used by `gift-cards` (the surface only appears once the user enables the Wix Gift Card app from the dashboard).
-
-A pack can be `include: true, disabled: true` (always loaded but never auto-active) or any other combination — they don't conflict.
-
-## How the skill uses the vertical
-
-1. **Discovery step**: scan loaded verticals for `features`, `routes`, `cmsCollections` → assemble plan markdown.
-2. **Setup phase**: collect `apps`, `packages` → one MCP call per app, one `npm install` with merged package list.
-3. **Seed phase**: for each vertical with a `seed` block, dispatch `seed.agent + scope`.
-4. **Design System phase**: Design System agent writes global styling — `@theme` token contract + a small set of always-required global semantic classes (compound patterns, interactive states, JS targets). Layout/spacing/typography flows through tokens-as-utilities at call sites; see `references/shared/STYLING.md`.
-5. **Components phase**: for each vertical with a `components` block, dispatch `components.agent + scope` (parallel).
-6. **Pages phase**: for each vertical, launch one agent per `pages[*]` entry (parallel).
+| `name` | string | yes | Matches filename stem (`stores.md` → `name: stores`) |
+| `description` | string | yes | One-line label — what the pack provides |
+| `triggers` | string[] | yes (empty allowed for transitive-only packs) | Case-insensitive substrings. SKILL.md routing table is the actual source of truth for what gets loaded; this is human reference. |
+| `requires` | string[] | no | Verticals that must be co-loaded in the same read batch |
+| `features` | object[] | yes | `{name, description}` — used in DISCOVERY.md Step 3 Section B |
+| `apps` | object[] | no | Zero or one entry. `apps[0].name` fills the Source column of the Pages table; absence implies built-in (cms uses `"CMS (builtin)"` literal). |
+| `routes` | object[] | no | `{route, name?}` — one row per entry in the Pages table |
+| `disabled` | bool | no | If true, the pack's surfaces are inactive by default. DISCOVERY plan skips disabled packs from Sections B + C. Today only `gift-cards`. Default false. |
+
+## How discovery uses the pack
+
+1. The orchestrator reads the user prompt and the SKILL.md routing table to determine the resolved pack set (top-level + `requires:` chain + always-on `cms`).
+2. It reads every pack file in the resolved set in **one concurrent batch**.
+3. From each pack's frontmatter it assembles:
+   - **Section B (interactive only)** — `features[].name` + `features[].description`, skipping packs with `disabled: true`.
+   - **Section C — Pages table** — one row per entry in `routes:` from non-disabled packs. Page cell uses `name:` override if present, else derives from the `route:` path. Source cell uses `apps[0].name`; for transitive packs, walk up the `requires:` chain to the top-level puller and use ITS `apps[0].name`. For `cms`, use the literal `"CMS (builtin)"`.
+4. Discovery never reads anything else from the pack file. Phase 2+ implementation work lives in the upstream skills.
 
 ## Adding a new vertical
 
-1. Create `<name>.md` in this directory with frontmatter per the schema above.
-2. Create `references/<name>/` with `INSTRUCTIONS.md` and `references/`.
-3. No changes needed to `SKILL.md` or other verticals.
-
-The skill discovers verticals by listing this directory. No registration step.
+1. Create `<name>.md` in this directory with the frontmatter above.
+2. Add a row to SKILL.md's routing table with the resolved pack set (top-level + transitive `requires:` + `cms`).
+3. No other registration needed.
 
 ## Validation (informal)
 
-The skill should sanity-check vertical frontmatter at load time:
-- `name` matches filename stem
-- `packages` non-empty (empty would mean nothing to install)
-- If `seed` is declared, `seed.agentLocation` exists on disk
-- If `components` or `pages` declared, their agent locations exist on disk
-- All declared `apps`, `routes`, `creates`, `contributes` paths are valid and don't collide with another loaded vertical's owned paths
+Sanity-check at session start:
+- `name` matches filename stem.
+- Every name in `requires:` resolves to a sibling file in this directory.
+- Every `route:` is either a `/`-prefixed path OR the literal string `"Hosted by Wix"`.
 
-If validation fails, fail loud — surface the error to the user. A malformed vertical breaking the whole flow is better than silently dropping it.
+If validation fails, fail loud — surface the error and stop. A malformed pack breaking the whole flow is better than silently dropping it.

package/skills/wix-headless/references/verticals/blog.md

@@ -1,7 +1,7 @@
 ---
 name: blog
+description: "Blog — post listing, post detail with rich content, RSS feed, sitemap."
 triggers: ["blog", "publish articles", "write posts", "content site", "editorial", "journal", "newsletter"]
-description: "Blog — post listing, post detail with rich content, RSS feed, sitemap"
 
 features:
   - name: "Blog"
@@ -13,113 +13,19 @@ apps:
   - name: "Wix Blog"
     appDefId: "14bcded7-0066-7c35-14d7-466cb3f09103"
 
-packages:
-  - "@wix/blog"
-  - "@wix/ricos"
-  - "@astrojs/rss"
-  - "@astrojs/sitemap"
-
 routes:
   - route: "/blog"
   - route: "/blog/[slug]"
     name: "Blog Post"   # path-derivation would produce "Blog [slug]" — override with the user-facing label
   - route: "/rss.xml"
 
-cmsCollections: []
-
-seed:
-  agentLocation: "references/blog/"
-  scope: "seed"
-  description: "Ensure Blog app is installed, seed 3 on-brand blog posts via MCP with rich Ricos content"
-  references: ["references/blog/BLOG_CONTENT.md"]
-
-components:
-  agentLocation: "references/blog/"
-  scope: "components"
-  description: "Blog service module (queryBlogPosts, getPostBySlug), RicosViewer React wrapper, site constants, astro.config sitemap integration"
-  references: ["references/blog/BLOG_SETUP.md"]
-  files:
-    - "src/lib/blog.ts"
-    - "src/components/RicosViewer.tsx"
-    - "src/consts.ts"
-    - "astro.config.mjs (patch — add site property and sitemap integration)"
-
-pages:
-  - name: "blog-pages"
-    agentLocation: "references/blog/"
-    scope: "pages"
-    description: "Wire blog listing + post detail pages to @wix/blog SDK, add RSS feed endpoint, BlogPost layout, SEO head, date formatting, patch home page latest-posts section"
-    references: ["references/blog/BLOG_PAGES.md"]
-    files:
-      - "src/pages/blog/index.astro"
-      - "src/pages/blog/[...slug].astro"
-      - "src/pages/rss.xml.js"
-      - "src/layouts/BlogPost.astro"
-      - "src/components/BaseHead.astro"
-      - "src/components/FormattedDate.astro"
-      - "src/pages/index.astro (patch — latest-posts section only)"
-
-creates:
-  - { file: src/lib/blog.ts,                  phase: components }
-  - { file: src/components/RicosViewer.tsx,   phase: components }
-  - { file: src/consts.ts,                    phase: components }
-  - { file: src/pages/blog/index.astro,       phase: pages }
-  - { file: src/pages/blog/[...slug].astro,   phase: pages }
-  - { file: src/pages/rss.xml.js,             phase: pages }
-  - { file: src/layouts/BlogPost.astro,       phase: pages }
-  - { file: src/components/BaseHead.astro,    phase: pages }
-  - { file: src/components/FormattedDate.astro, phase: pages }
-
-contributes:
-  - file: astro.config.mjs
-    marker: "<!-- config:sitemap -->"
-    description: "site property + @astrojs/sitemap integration"
-  - file: src/pages/index.astro
-    marker: "<!-- home:blog -->"
-    description: "Latest 3 posts grid (cover images, titles, dates, excerpts) from queryBlogPosts(3)"
-  - file: src/components/Navigation.astro
-    marker: "<!-- nav:links -->"
-    description: "Blog menu link → /blog"
-
-include: false
 disabled: false
 ---
 
 # Blog Pack
 
-Blog vertical for content-driven sites. Loaded when the user's prompt mentions blogging, publishing, or editorial content.
-
-## Phase decomposition
-
-| Scope | Phase | Files | Depends on |
-|-------|-------|-------|------------|
-| `seed` | Phase 1 — Step 3 (bg) | None (MCP only) | MCP connection |
-| `components` | Phase 3 — Step 4.5 (bg) | blog.ts, RicosViewer.tsx, consts.ts, astro.config.mjs | Styling contract |
-| `blog-pages` | Phase 4 — Step 7 (bg) | blog/index.astro, blog/[...slug].astro, rss.xml.js, BlogPost.astro, BaseHead.astro, FormattedDate.astro, index.astro (patch) | Phase 2 Design System + Phase 1 Seed post data |
-
-Phase 3 Components runs in the background from Step 4.5 through Phase 4. Phase 4 blog-pages dispatches in Step 7 after Phase 3 + Phase 1 Seed complete — it needs the React islands written by Phase 3 and the seeded post slugs from Phase 1.
-
-RSS feed generation (`rss.xml.js`) is included in the blog-pages scope rather than a separate scope — it's ~15 lines, has no design dependency, and doesn't justify its own agent dispatch.
-
-## Known failure modes (propagate to agent prompts)
-
-| Wrong | Right |
-|-------|-------|
-| `import { items } from "@wix/data"` for blog queries | `import { posts } from "@wix/blog"` — use the Blog SDK |
-| `<article set:html={post.content} />` | `<RicosViewer client:only="react" content={post.richContent} />` — content is Ricos format |
-| Skip `wixMetadata` export on `[...slug].astro` | Required for Wix page routing and SEO |
-| `media.wixMedia.image` as raw URL | `media.getImageUrl(item.media.wixMedia.image).url` — must resolve |
-| Query posts without `RICH_CONTENT` fieldset | Always request `RICH_CONTENT` or `post.richContent` is undefined |
-| `const { tag } = await tags.getTag(id)` | `const tag = await tags.getTag(id)` — returns directly (unlike `getCategory()`) |
-| Scoped `<style>` for RicosViewer overrides | `<style is:global>` — React islands don't inherit scoped Astro styles |
-| Skip `.ricos-content` color overrides | Ricos CSS hardcodes `color: rgb(0, 0, 0)` — invisible on dark themes without overrides |
-
-## Images
-
-Cover images for blog posts are generated by the shared image agent (`image-phase-2-entity` scope), not by blog agents. The image agent PATCHes cover images onto post records after Phase 1 Seed creates them. Phase 4 agents query posts and render `post.media` — the image URL flows through the post record.
-
-## References
+Loaded when the user's prompt mentions blogging, publishing, or editorial content.
 
-- `references/blog/BLOG_CONTENT.md` — Phase 1: MCP post seeding
-- `references/blog/BLOG_SETUP.md` — Phase 3 Components: service module, RicosViewer, config
-- `references/blog/BLOG_PAGES.md` — Phase 2 blog-pages: listing, detail, RSS, layout, SEO
+> **Discovery contract.** Phase 1 reads only the frontmatter above. Phase 2+ implementation (post seeding, RSS, page composition, ricos rendering) lives in an upstream skill plus this skill's own `templates/blog/` + `references/blog/INSTRUCTIONS.md`:
+>
+> - `@skills/wix-manage` ships the seeding recipe — `references/blog/how-to-create-blog-posts.md`.