@se-studio/skills 1.5.1 → 1.5.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.5.3
+
+### Patch Changes
+
+- Add `task-media-review` editor playbook with production URL support, registry entry, and updated media-review skills for multi-customer Claude workflows.
+
+## 1.5.2
+
+### Patch Changes
+
+- Cap `asset review --include-usage` with `--usage-limit` (default 50) to avoid hosted MCP timeouts on large spaces. Document usage-limit in asset-review help and media-review skill.
+
 ## 1.5.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/skills/contentful-cms-editor-tasks/SKILL.md

@@ -64,6 +64,8 @@ Capability playbooks require:
 
 **Search and reuse assets first** (`index sync` → `asset search`). Upload only when no match; use `--if-exists-by-filename` when uploading.
 
+**Space-wide media audit** (filename, alt, size, dimensions, usage) → read **`task-media-review`**, then skill **`contentful-cms-media-review`** for the spreadsheet.
+
 ## When the pack is stale
 
 Run `contentful-cms-regenerate-editor-pack` after:
@@ -80,4 +82,5 @@ Then `cms-edit project doctor --project-config cms-edit/<site>/project.json`.
 |-------|------|
 | `contentful-cms-core` | CLI command reference |
 | `contentful-cms-setup` | First-time hosted MCP connect |
-| `contentful-cms-regenerate-editor-pack` | Refresh editor-pack in git |
+| `contentful-cms-regenerate-editor-pack` | Refresh editor-pack in git |
+| `contentful-cms-media-review` | Space-wide asset audit + Excel report |

package/skills/contentful-cms-media-review/SKILL.md

@@ -1,170 +1,96 @@
 ---
 name: contentful-cms-media-review
-description: "Audit CMS images, videos, and Lottie animations for filename, alt text, dimensions, size, and GIF issues using cms-edit, then produce an Excel report of failures."
+description: "Audit CMS images, videos, and Lottie animations using the task-media-review editor playbook and cms-edit asset review, then produce an Excel report."
 ---
 
 # Skill: contentful-cms — Media Review
 
-Use this skill to audit **visual assets** in a Contentful space and produce a spreadsheet of assets that fail quality checks.
+Use this skill for a **space-wide visual asset audit** and spreadsheet deliverable.
 
-## When to use
+## Start here (every site)
 
-- Cleaning up CMS media before or after a migration
-- Finding oversized images, missing alt text, or animated GIFs
-- Brightline, SE Studio, or any site with `cms-edit` configured
+1. **`contentful-cms-editor-tasks`** — route to the site playbook
+2. Read **`task-media-review`** before running commands:
+   - **Hosted MCP:** `cms_edit ["customer", "task-media-review"]`
+   - **Local:** `cms-edit/<site>/editor-pack/task-media-review.md`
+3. Read **`overview`** for `productionSiteUrl` (prod link columns)
 
-## Prerequisites
-
-- `cms-edit` configured for the target space (`cms-edit health`)
-- `CONTENTFUL_PREVIEW_ACCESS_TOKEN` set (default index uses Preview API / drafts)
-- Run `cms-edit index sync` before the review if the index is stale
-
-## Workflow
-
-### Step 1 — Sync the index
-
-```bash
-cms-edit index sync --space <space-key>
-```
+The playbook defines phases, hosted vs local limits, and confirmation gates. This skill covers **spreadsheet schema** and **optional image guide**.
 
-Use `--published` only when you want published/delivery content only.
-
-### Step 2 — Run the review
+## Prerequisites
 
-```bash
-cms-edit --json asset review --space <space-key> > /tmp/media-review.json
-```
+- `cms-edit health` (or hosted connector healthy)
+- `CONTENTFUL_PREVIEW_ACCESS_TOKEN` (default Preview index)
+- `CMS_EDIT_TOKEN` when using `--include-usage`
+- `cms-edit index sync` if index is stale
 
-Optional flags:
+## Quick command reference
 
-| Flag | Purpose |
+| Goal | Command |
 |------|---------|
-| `--include-passing` | Include assets with no failures |
-| `--max-width 2000` | Max raster/video width (default 2000) |
-| `--max-image-kb 800` | Max image file size |
-| `--max-video-mb 8` | Max video file size |
-| `--max-lottie-kb 400` | Max Lottie JSON size |
-| `--published` | Use Delivery API index |
+| Failures JSON | `cms-edit --json asset review` |
+| Full + usage (local) | `cms-edit --json asset review --include-passing --include-usage --usage-limit 0` |
+| Usage sample (hosted) | `cms-edit --json asset review --include-usage --usage-limit 50` |
 
-Exit code **1** when any asset has failing issues (useful for CI).
+Hosted MCP: **no `--space`**. Do not use `--usage-limit 0` with `--include-passing` on hosted MCP.
 
-### Step 3 — Build the Excel report
+## Excel workbook (failures)
 
-Create a workbook with **failures only** (default JSON output). Use the **xlsx** skill.
+Use the **xlsx** skill. Default path: `docs/media-review-<projectKey>-<date>.xlsx`.
 
 **Sheet: Issues** — one row per failing asset
 
-| Column | Source field |
-|--------|----------------|
+| Column | Source |
+|--------|--------|
 | Asset ID | `assets[].id` |
 | Contentful URL | `assets[].contentfulUrl` |
 | CDN URL | `assets[].url` |
-| Title | `assets[].title` |
-| Filename | `assets[].fileName` |
-| Alt text | `assets[].description` |
-| Content type | `assets[].contentType` |
-| Width | `assets[].width` |
-| Height | `assets[].height` |
-| Size (KB) | `assets[].sizeKb` |
-| Media wrappers | `assets[].mediaEntryCount` |
-| Issue codes | `assets[].issues[].code` (comma-separated fails) |
-| Issue details | `assets[].issues[].message` (semicolon-separated) |
-| Updated | `assets[].updatedAt` |
-
-**Sheet: Summary**
-
-- `space`, `spaceId`, `environment`, `generated`, `preview`
-- `total`, `failingCount`, `warningCount`
-- `issueCounts` breakdown
-- Thresholds from `thresholds` object
-
-Default output path: `docs/media-review-<space>-<date>.xlsx` in the app directory.
-
-### Step 4 — Present findings
-
-Summarize for the user:
-
-- Total assets scanned vs failures
-- Top issue types (from `issueCounts`)
-- Quick wins (missing alt, animated GIFs, obvious stock filenames)
-- Note: `no_media_wrapper` is a **warning** — asset may still be used via rich text or be genuinely unused
-
-## What is checked
-
-| Check | Issue code | Severity |
-|-------|------------|----------|
-| Descriptive filename | `bad_filename` | fail |
-| Alt text present | `missing_alt` | fail |
-| Alt text quality | `weak_alt` | fail |
-| Width ≤ max (not SVG/Lottie) | `oversized_width` | fail |
-| File size limits | `oversized_file` | fail / warn |
-| Animated GIF | `animated_gif` | fail |
-| No media wrapper in index | `no_media_wrapper` | warn |
-
-## Brightline example
+| Title / Filename / Alt | `title`, `fileName`, `description` |
+| Content type | `contentType` |
+| Width / Height / Size (KB) | `width`, `height`, `sizeKb` |
+| Media wrappers | `mediaEntryCount` |
+| CMS usages | `usages[].slug` + `label` (when `--include-usage`) |
+| Prod URLs | `{productionSiteUrl}{slug}` from overview/capabilities |
+| Issue codes | fail-severity `issues[].code` |
+| Issue details | `issues[].message` |
+| Likely unused | empty `usages` + `no_media_wrapper` warn |
+| Updated | `updatedAt` |
 
-```bash
-cd apps/brightline-website
-cms-edit index sync --space brightline
-cms-edit --json asset review --space brightline > /tmp/brightline-media-review.json
-```
+**Sheet: Summary** — `total`, `failingCount`, `issueCounts`, `thresholds`, `usageTruncated` if applicable
 
-Space key: `brightline` (space ID `96gdpqkm7elu`).
+## Issue codes
 
-## Phase 2 (not yet in cms-edit)
+| Code | Severity |
+|------|----------|
+| `bad_filename` | fail |
+| `missing_alt` / `weak_alt` | fail |
+| `oversized_width` | fail |
+| `oversized_file` | fail / warn |
+| `animated_gif` | fail |
+| `no_media_wrapper` | warn |
 
-Production page URLs and definitive unused-asset detection need CMA `links_to_asset` or a production crawl. When available, add columns `prodUrls` and `cmsUsages` to the spreadsheet.
+## After the spreadsheet
 
-## Image guide (optional)
+Summarize: totals, top `issueCounts`, quick wins (alt, GIFs, stock filenames).
 
-Use this extension when the client wants a **reference guide** for all CMS images (Markdown + HTML), not just a quality spreadsheet.
+**Fixes (user-approved only):** `cms-edit asset set-description <id> "…"` — drafts only, no publish.
 
-### Gather structural data
+For per-page alt work: **`contentful-cms-alt-text-audit`**.
 
-```bash
-cms-edit index sync --space <space-key>
-cms-edit --json asset review --include-usage --include-passing --space <space-key> > /tmp/image-inventory.json
-```
-
-Each asset in JSON includes `usages[]`: slug-bearing ancestors (page, article, tag, person, etc.) that ultimately use the asset.
-
-To inspect how images relate to a specific page, use `cms-edit open --page-slug /<slug>` + `snapshot`, or `cms-edit peek --page-slug /<slug>` without affecting your session.
-
-### Description cache
-
-Store AI-generated visual descriptions per asset (avoids re-inspecting on reruns):
+## Image guide (optional extension)
 
-```
-docs/descriptions/{assetId}.json
-```
+When the client wants a **reference guide** (not just remediation):
 
-Per-image format:
-
-```json
-{
-  "subjects": "...",
-  "setting": "...",
-  "composition": "...",
-  "colours": "...",
-  "mood": "...",
-  "style": "...",
-  "constraints": "...",
-  "whenToUse": "...",
-  "inspectedAt": "2026-04-15T10:00:00Z"
-}
+```bash
+cms-edit --json asset review --include-passing --include-usage --usage-limit 0 > docs/image-inventory.json
 ```
 
-**Write-through caching:** After inspecting each new image, write `docs/descriptions/{assetId}.json` before moving to the next. Skip vision calls when the cache file exists.
-
-### Output files
-
-- `docs/image-guide.md` — AI-consumable Markdown (chunk writes: ~35 images per append)
-- `docs/image-guide.html` — self-contained human reference (chunk writes: ~15–20 cards per append)
-
-Use CDN URLs with `?w=800&q=85` for previews. Group entries by page using `usages[]` from the review JSON.
+- Cache AI descriptions: `docs/descriptions/{assetId}.json` (write-through per image)
+- Outputs: `docs/image-guide.md`, `docs/image-guide.html`
+- CDN previews: `?w=800&q=85`
 
 ## Related
 
-- `contentful-cms-alt-text-audit` — per-page alt text fixes
-- `cms-edit asset audit` — missing alt only (narrower, faster)
-- `cms-edit asset set-description <id> "alt"` — fix alt text on an asset
+- `cms-edit help asset-review` — CLI flags
+- `task-media-reuse-and-upload` — upload/search workflow
+- `cms-edit asset audit` — missing alt only (narrower)

package/skills/contentful-cms-regenerate-editor-pack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: contentful-cms-regenerate-editor-pack
-description: "Regenerate cms-edit editor-pack for hosted MCP after registrations, guidelines, routing, or cms-editor docs change; validate, commit, and deploy."
+description: "Regenerate cms-edit editor-pack for hosted MCP after registrations, guidelines, routing, or cms-editor docs change; validate, commit, and push (never manual vercel deploy)."
 ---
 
 # Regenerate cms-edit editor pack
@@ -83,28 +83,23 @@ git add cms-edit/editor-pack   # or cms-edit/<site>/editor-pack
 git commit -m "chore(cms-edit): regenerate editor pack"
 ```
 
-## Step 6 — Deploy
+## Step 6 — Publish (commit + push only)
 
-### Customer repo with `cms-edit/host/` (SE Studio, Pedestal, Headwater)
+**Absolute rule for agents:** hosted MCP is **never** published via `vercel deploy`, `pnpm cms-edit:deploy*`, or `deploy-cms-edit-host.sh`. Commit and push is the only deploy path for customer repos with `cms-edit/host/`.
 
-Commit `editor-pack/`, then push to the branch Vercel watches (usually `develop`). Changes under `cms-edit/**` trigger a host rebuild (`stage-site.mjs` copies committed artifacts).
+### Customer repo with `cms-edit/host/` (SE Studio, Pedestal, Headwater, Brightline, …)
+
+Commit `editor-pack/` (and any other `cms-edit/**` changes), then push to the branch Vercel watches (usually `develop`). Changes under `cms-edit/**` trigger a host rebuild (`stage-site.mjs` copies committed artifacts on the Vercel build).
 
 ```bash
-git push
+git push origin develop   # or the site's configured deploy branch
 ```
 
-Manual deploy without pushing: `pnpm cms-edit:deploy` (single-site) or `pnpm cms-edit:deploy:<site>` (multi-site) — runs validate, stage, then `vercel deploy --prod` **from the repo root** with `--project <vercel-project>`. Do not `cd cms-edit/host` first (Vercel Root Directory is already `cms-edit/host`).
+Do **not** run `pnpm cms-edit:deploy` or `vercel deploy` after this step.
 
 ### Customers without `cms-edit/host/` in their repo
 
-From `se-core-product`:
-
-```bash
-./scripts/deploy-cms-edit-host.sh \
-  --config <customer-repo>/cms-edit/<site>/project.json \
-  --editor-pack <customer-repo>/cms-edit/<site>/editor-pack \
-  --prod
-```
+Rare layout — coordinate with the repo owner. Agents still must not run deploy scripts unless explicitly asked.
 
 ## Homepage slug reminder