@se-studio/skills 1.2.3 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.3.1
+
+### Patch Changes
+
+- Move CMS guidelines prompt pack from `skills/` to `references/` so skills-npm no longer reports `file_error` for `contentful-cms-cms-guidelines`. Update pipeline doc links in CMS guideline skills.
+
+## 1.3.0
+
+### Minor Changes
+
+- Add `screaming-frog-audit` agent skill for Screaming Frog crawl, native compare, and prioritized audit workflows.
+
 ## 1.2.3
 
 ### Patch Changes

package/README.md

@@ -21,6 +21,15 @@ npx skills add @se-studio/skills
 
 Auto-sync on `pnpm install` (see [`packages/project-build/README.md`](../project-build/README.md) for the full `package.json` snippet). Use `pnpm skills:sync` manually to add or refresh third-party skill packs.
 
+## Package layout
+
+| Path | Purpose |
+|------|---------|
+| `skills/<name>/SKILL.md` | Agent skills — the only directories scanned by `skills-npm` and the skills CLI |
+| `references/<name>/` | Support docs, prompt packs, and pipeline references (no `SKILL.md`) |
+
+Do **not** place non-skill material under `skills/` — directories there without `SKILL.md` cause `file_error` warnings in consumer repos on `pnpm install`.
+
 ## Authoring skills
 
 Canonical sources live in `packages/skills/skills/<skill-dir>/SKILL.md`. Do **not** edit `.agents/skills/` by hand.
@@ -56,7 +65,7 @@ Claude Code uses a naive frontmatter parser; violations cause descriptions to si
 
 1. Edit `packages/skills/skills/<skill-dir>/SKILL.md`
 2. Validate: `pnpm skills:validate`
-3. Sync: `pnpm skills:sync`
+3. Sync: `pnpm skills:sync` (copies `skills/` → `.agents/skills/` and `references/` → `.agents/references/`)
 4. Add a changeset if publishing `@se-studio/skills`
 
 ### cms-edit bundled skills (`@se-studio/contentful-cms`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",
@@ -10,6 +10,7 @@
   "license": "MIT",
   "files": [
     "skills",
+    "references",
     "*.md"
   ],
   "keywords": [

package/{skills → references}/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](../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](../../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.
 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](../contentful-cms-generate-cms-guidelines/SKILL.md).
+5. **Generate guidelines** — run the [Generate CMS guidelines skill](../../skills/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 [`../contentful-cms-generate-cms-guidelines/SKILL.md`](../contentful-cms-generate-cms-guidelines/SKILL.md). It supports three modes:
+Use the Cursor skill at [`../../skills/contentful-cms-generate-cms-guidelines/SKILL.md`](../../skills/contentful-cms-generate-cms-guidelines/SKILL.md). It supports three modes:
 
 | Mode | When to use |
 |---|---|

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

@@ -479,10 +479,16 @@ cms-edit types component
 cms-edit types collection
 
 # List entries with filters
+cms-edit list --type article --sort date -n 10     # recent articles by publication date
 cms-edit list --type article --has-download       # articles with a download asset
 cms-edit list --type article --slug my-article    # article with a specific slug
 cms-edit list --type article --has-field tags      # articles where tags field is non-empty
 
+# Find draft articles, then peek/open (both support drafts via CMA)
+cms-edit sitemap --include article --status draft
+cms-edit peek --article-slug resources/blog/my-post
+# Only list --published / resolve --published are published-only
+
 # Resolve any entry or asset by ID (no open session required)
 cms-edit resolve --id 4xKj2abcDefGhijK             # entry: shows type, title, slug, status
 cms-edit resolve --id 7pQrStuvWxyzAbc              # asset: shows title, fileName, URL
@@ -702,6 +708,7 @@ cms-edit sitemap                         # All pages, sorted by slug
 cms-edit sitemap --prefix /blog          # Filter by slug prefix
 cms-edit sitemap --status draft          # Draft pages only
 cms-edit sitemap --sort updated          # Most recently updated first
+cms-edit sitemap --include article --sort date  # Articles by publication date
 cms-edit sitemap --tree                  # Tree rendering
 cms-edit sitemap --include page,article  # Include articles too
 ```

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

@@ -197,9 +197,9 @@ IMPORTANT: Screenshots have already been captured. Skip Phase A entirely.
 Go straight to Phase B.
 
 Files to read before starting:
-- ../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)
+- ../../references/contentful-cms-cms-guidelines/generation-prompt.md  (Phase B instructions)
+- ../../references/contentful-cms-cms-guidelines/colour-hint-prompt.md  (Phase C instructions)
+- ../../references/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

@@ -112,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
-[`generate-component-guidelines.md`](../contentful-cms-cms-guidelines/generate-component-guidelines.md).
+[`generate-component-guidelines.md`](../../references/contentful-cms-cms-guidelines/generate-component-guidelines.md).
 
 To find unfinished components:
 1. Fetch `<discoveryUrl>` and collect all `components[].name` values.
@@ -128,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 (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)
+Read these pipeline docs first (references/contentful-cms-cms-guidelines/):
+- ../../references/contentful-cms-cms-guidelines/generate-component-guidelines.md  (overall pipeline)
+- ../../references/contentful-cms-cms-guidelines/variant-loop.md                   (Phase A: variant loop)
+- ../../references/contentful-cms-cms-guidelines/generation-prompt.md              (Phase B: generation)
+- ../../references/contentful-cms-cms-guidelines/colour-hint-prompt.md             (Phase C: colour hint)
+- ../../references/contentful-cms-cms-guidelines/validation-prompt.md              (Phase D: validation)
 
 === Phase A: Variant loop ===
 Follow variant-loop.md.
@@ -282,7 +282,7 @@ These links:
 
 ## Pipeline reference
 
-All per-component pipeline docs live in the sibling directory [`contentful-cms-cms-guidelines/`](../contentful-cms-cms-guidelines/):
+All per-component pipeline docs live in [`references/contentful-cms-cms-guidelines/`](../../references/contentful-cms-cms-guidelines/):
 
 | File | Purpose |
 |---|---|

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

@@ -338,4 +338,4 @@ Follow [`../contentful-cms-regenerate-editor-pack/SKILL.md`](../contentful-cms-r
 | 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) |
 | Regenerate hosted editor pack | [`../contentful-cms-regenerate-editor-pack/SKILL.md`](../contentful-cms-regenerate-editor-pack/SKILL.md) |
-| Per-component pipeline detail | [`generate-component-guidelines.md`](../contentful-cms-cms-guidelines/generate-component-guidelines.md) |
+| Per-component pipeline detail | [`generate-component-guidelines.md`](../../references/contentful-cms-cms-guidelines/generate-component-guidelines.md) |

package/skills/screaming-frog-audit/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: screaming-frog-audit
+description: "Crawl a marketing site with Screaming Frog, run native compare mode between crawls, and generate prioritized audit/compare reports via @se-studio/site-check and seo/screaming-frog.json."
+---
+
+# Screaming Frog crawl, compare, and audit
+
+Use when the user wants a Screaming Frog crawl, before/after deployment comparison, or SEO issue audit (404s, canonicals, structured data, content/metadata regressions).
+
+**Requires:** Screaming Frog SEO Spider (licensed), **database storage mode** (default with `--save-crawl`).
+
+**Config:** each app's `seo/screaming-frog.json` — no site-specific presets in core product.
+
+---
+
+## Deployment workflow (content push → code release)
+
+Typical process: crawl after CMS/content is on preview, then crawl again after code ships, and confirm no significant content/metadata regressions.
+
+### 1. Baseline after content push
+
+From the app directory:
+
+```bash
+pnpm seo:screaming-frog:baseline
+# equivalent:
+site-check-screaming-frog crawl --tag content
+```
+
+This crawls with the manifest profile, saves to SF's database, and records the database ID as baseline `content` in `docs/seo/sf-crawl-state.json`.
+
+### 2. Crawl after code release
+
+```bash
+pnpm seo:screaming-frog:crawl
+```
+
+Records the new crawl as `lastCrawl` in `sf-crawl-state.json`.
+
+### 3. Native compare (before vs after)
+
+```bash
+pnpm seo:screaming-frog:compare
+# equivalent:
+site-check-screaming-frog compare --baseline content
+```
+
+Uses Screaming Frog **`--crawl-comparison <current-db-id> <previous-db-id>`** (native Compare mode), exports Change Detection CSVs, and writes `docs/seo/<site>-screaming-frog-compare.md`.
+
+Exit code 1 when title/meta/H1/word-count regressions are detected.
+
+### 4. Optional full issue audit
+
+```bash
+pnpm seo:screaming-frog ~/spider/exports/<timestamp>
+```
+
+Prioritized P0–P3 report from a single crawl export.
+
+---
+
+## Other commands
+
+```bash
+site-check-screaming-frog profiles          # show crawl profiles from manifest
+site-check-screaming-frog list-crawls     # SF database IDs for this siteHost
+site-check-screaming-frog compare --latest   # two most recent crawls (same host)
+site-check-screaming-frog compare <current-id> <previous-id>  # explicit IDs
+```
+
+---
+
+## What native compare checks
+
+SF Change Detection exports (current vs previous on **matched URLs**):
+
+- Page titles, meta descriptions, H1
+- Word count (flags ≥50 words or ≥10% change)
+- Indexability status
+- Structured data type changes (via dedicated export tab)
+
+Does **not** replace a full audit for new 404s — run `audit` on the post-release export for issue triage.
+
+---
+
+## Prerequisites
+
+| Item | Notes |
+|------|-------|
+| SF GUI | Quit before CLI crawl/compare (shared DB lock) |
+| Vercel preview | Bypass header in `.seospiderconfig`; `PREVIEW_SITE_URL` in `.env.local` |
+| Same profile | Compare only meaningful when both crawls use the same URL/profile |
+| Database storage | `--save-crawl` stores crawls; compare needs two DB IDs |
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| 0 matched URLs in compare | Different URLs/host between crawls — use same profile |
+| No baseline | Run `crawl --tag content` first |
+| GUI lock / FATAL | Quit Screaming Frog app |
+| Wrong crawls picked | `list-crawls` then pass explicit database IDs |

package/skills/screaming-frog-audit/references/profiles.md

@@ -0,0 +1,62 @@
+# Screaming Frog site config
+
+Each project owns **`seo/screaming-frog.json`** at the app root (or pass `--config` explicitly). The core product package has no built-in site presets.
+
+## Required fields
+
+| Field | Purpose |
+|-------|---------|
+| `site` | Short site key (for logging) |
+| `siteLabel` | Display name in audit report |
+| `siteHost` | Host substring for filtering redirect samples |
+| `defaultSiteUrl` | Fallback URL when crawl overview is missing |
+| `outputMdName` | Audit markdown filename (written under `docs/seo/`) |
+| `profiles` | Named crawl targets with `configFile` paths |
+
+## Optional fields
+
+| Field | Purpose |
+|-------|---------|
+| `defaultProfile` | Profile used when `--profile` is omitted |
+| `productionAuditDoc` | Cross-link in report to live HTML audit doc |
+| `issueRuleOverrides` | Per-site P0–P3 rule tweaks (merged over base rules in `@se-studio/site-check`) |
+
+## Example manifest
+
+```json
+{
+  "site": "brightline",
+  "siteLabel": "Brightline",
+  "siteHost": "hellobrightline.com",
+  "defaultSiteUrl": "https://www.hellobrightline.com/",
+  "outputMdName": "brightline-screaming-frog-audit.md",
+  "defaultProfile": "preview",
+  "issueRuleOverrides": [
+    {
+      "match": "directives_noindex",
+      "tier": "p2",
+      "category": "indexing",
+      "note": "Expected on Vercel preview."
+    }
+  ],
+  "profiles": {
+    "production": {
+      "label": "Production",
+      "url": "https://www.hellobrightline.com/",
+      "configFile": "~/spider/bl production.seospiderconfig"
+    },
+    "preview": {
+      "label": "Vercel preview",
+      "urlEnv": "PREVIEW_SITE_URL",
+      "configFile": "~/spider/bl dev.seospiderconfig"
+    },
+    "localhost": {
+      "label": "Local dev",
+      "url": "http://localhost:3010/",
+      "configFile": "~/spider/bl localhost.seospiderconfig"
+    }
+  }
+}
+```
+
+`.seospiderconfig` files live outside the repo (typically `~/spider/`). Preview configs should embed the Vercel bypass header.