ci(skills): gate PRs on skill-docs being generated from SKILL.md frontmatter (#1844)

Adds a `Check Skill Docs` job to ci.yml, gated (via paths-filter) on changes to
`skills/**`, `content/docs/guides/skills.mdx`, or the generator script. It runs
`pnpm --filter @objectstack/spec check:skill-docs`, which fails if the README
index or guide tables/cards drift from each SKILL.md frontmatter — closing the
loop so the catalog can never silently go stale again.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.changeset/ci-check-skill-docs.md

@@ -0,0 +1,7 @@
+---
+---
+
+ci: add a `Check Skill Docs` job that runs `check:skill-docs` on PRs touching
+`skills/**`, the skills guide, or the generator — failing if the generated
+README/guide listings drift from the `SKILL.md` frontmatter. CI-only, no
+package change.

.github/workflows/ci.yml

@@ -17,10 +17,11 @@ jobs:
     outputs:
       docs: ${{ steps.changes.outputs.docs }}
       core: ${{ steps.changes.outputs.core }}
+      skilldocs: ${{ steps.changes.outputs.skilldocs }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-      
+
       - uses: dorny/paths-filter@v4
         id: changes
         with:
@@ -30,6 +31,11 @@ jobs:
               - 'content/**'
               - 'pnpm-lock.yaml'
               - '.github/workflows/ci.yml'
+            skilldocs:
+              - 'skills/**'
+              - 'content/docs/guides/skills.mdx'
+              - 'packages/spec/scripts/build-skill-docs.ts'
+              - '.github/workflows/ci.yml'
             core:
               - 'packages/**'
               - 'examples/**'
@@ -224,3 +230,42 @@ jobs:
 
       - name: Build Docs
         run: pnpm --filter @objectstack/docs build
+
+  check-skill-docs:
+    name: Check Skill Docs
+    needs: filter
+    if: needs.filter.outputs.skilldocs == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v5
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-v3-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-v3-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check skill docs are generated from SKILL.md frontmatter
+        run: pnpm --filter @objectstack/spec check:skill-docs