From 11d22d1b5820740713d763db26439accc81e5927 Mon Sep 17 00:00:00 2001
From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Date: Sun, 14 Jun 2026 12:58:24 +0500
Subject: [PATCH] ci(skills): gate PRs on skill-docs being generated from
 SKILL.md frontmatter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/ci-check-skill-docs.md |  7 +++++
 .github/workflows/ci.yml          | 47 ++++++++++++++++++++++++++++++-
 2 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/ci-check-skill-docs.md

diff --git a/.changeset/ci-check-skill-docs.md b/.changeset/ci-check-skill-docs.md
new file mode 100644
index 0000000000..47ba49b40c
--- /dev/null
+++ b/.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.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index beb5bfe200..9230270f92 100644
--- a/.github/workflows/ci.yml
+++ b/.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