ci: enforce per-skill SKILL.md version bump on content change (#4)

The existing validate-version job catches forgotten plugin.json bumps,
but says nothing when a specific skill's content changes without that
skill's own metadata.version moving. Add a second step in the same
job that:

  1. Diffs against the PR base for paths under skills/<name>/**
  2. For each affected skill, parses metadata.version out of SKILL.md
     on base and head
  3. Fails unless the head version is strictly greater (semver-sorted)

Skips skills that are new on the branch or were deleted, and fails
loud if metadata.version is not semver. Moves BASE_SHA to job-level
env so both steps share it.

AGENTS.md updated to document the expanded check and the resulting
expectation that skill content changes also bump SKILL.md
metadata.version.

Author: DaleSeo

.github/workflows/ci.yml

@@ -12,6 +12,8 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    env:
+      BASE_SHA: ${{ github.event.pull_request.base.sha }}
 
     steps:
       - name: Checkout repository
@@ -20,8 +22,6 @@ jobs:
           fetch-depth: 0
 
       - name: Verify plugin.json#version bumped if skills/ or .claude-plugin/ changed
-        env:
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
         run: |
           base=$(git show "$BASE_SHA":.claude-plugin/plugin.json | jq -r .version)
           head=$(jq -r .version .claude-plugin/plugin.json)
@@ -42,7 +42,47 @@ jobs:
             fi
           fi
 
-          echo "✅ version check passed"
+          echo "✅ plugin version check passed"
+
+      - name: Verify SKILL.md#version bumped if skill content changed
+        if: always()
+        run: |
+          changed_skills=$(git diff --name-only "$BASE_SHA"...HEAD -- 'skills/*/**' \
+            | awk -F/ 'NF>=3 {print $2}' | sort -u)
+          if [ -z "$changed_skills" ]; then
+            echo "✅ No skill content changed; per-skill version bump not required."
+            exit 0
+          fi
+          extract_version() {
+            awk '/^---$/{c++; next} c==1' | yq -r '.metadata.version // ""'
+          }
+          fail=0
+          for skill in $changed_skills; do
+            head_file="skills/$skill/SKILL.md"
+            if [ ! -f "$head_file" ]; then
+              echo "ℹ️  $skill: SKILL.md missing on HEAD (skill deleted); skipping."
+              continue
+            fi
+            base_content=$(git show "$BASE_SHA:$head_file" 2>/dev/null || true)
+            if [ -z "$base_content" ]; then
+              echo "ℹ️  $skill: new skill on this branch; skipping bump check."
+              continue
+            fi
+            head_v=$(extract_version < "$head_file")
+            base_v=$(printf '%s\n' "$base_content" | extract_version)
+            if [[ ! "$head_v" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+              echo "❌ $skill: SKILL.md metadata.version is not semver: '$head_v'"
+              fail=1
+              continue
+            fi
+            if [ "$head_v" = "$base_v" ] || ! printf '%s\n%s\n' "$base_v" "$head_v" | sort -V -C; then
+              echo "❌ $skill: content changed but SKILL.md metadata.version did not strictly increase ($base_v → $head_v). Bump the patch version for bug fixes."
+              fail=1
+              continue
+            fi
+            echo "✅ $skill: $base_v → $head_v"
+          done
+          exit $fail
 
   validate-spec:
     runs-on: ubuntu-latest

AGENTS.md

@@ -119,7 +119,7 @@ Each skill follows the Agent Skills specification:
 
 `.github/workflows/ci.yml` runs on every PR and main push with five jobs:
 
-- **`validate-version`** (PR only): Fails the PR if anything under `skills/` or `.claude-plugin/` changed without bumping `.claude-plugin/plugin.json#version`. Prevents shipping silent updates.
+- **`validate-version`** (PR only): Two checks. (1) Fails if anything under `skills/` or `.claude-plugin/` changed without bumping `.claude-plugin/plugin.json#version`. (2) For each skill whose content changed under `skills/<name>/**`, fails if the skill's own `SKILL.md` `metadata.version` did not strictly increase. Prevents shipping silent updates at both the plugin and individual-skill level.
 - **`validate-spec`**: Validates each `SKILL.md` against the Agent Skills spec using `skills-ref validate` (from `agentskills/agentskills`).
 - **`validate-publish`**: Runs `gh skill publish --dry-run` to check publishability before main merges.
 - **`install-local`**: Installs all skills from the local working tree via `npx skills add "$GITHUB_WORKSPACE" --yes` and verifies each skill landed in `.agents/skills/`.
@@ -138,7 +138,7 @@ Three places carry version numbers, but only one matters operationally.
 
 Use semver: patch for fixes/wording, minor for new skills or pattern additions, major when removing or renaming a skill.
 
-**Individual `SKILL.md#version`** (e.g. humanizer 1.6.0) — independent of the plugin version. Track skill-internal evolution there. The plugin version doesn't have to follow the highest skill version — they're separate trackers, like Apollo's pattern (apollo-skills plugin at 1.2.x while internal skills are at various 1.x).
+**Individual `SKILL.md#version`** (e.g. humanizer 1.6.0) — independent of the plugin version. Track skill-internal evolution there. The plugin version doesn't have to follow the highest skill version — they're separate trackers, like Apollo's pattern (apollo-skills plugin at 1.2.x while internal skills are at various 1.x). When a PR modifies any file under `skills/<name>/`, the `validate-version` job requires that skill's `metadata.version` to strictly increase (semver patch is enough for bug fixes).
 
 **`marketplace.json#metadata.version` and `marketplace.json#plugins[0].version`** — keep aligned with `plugin.json#version` for tidiness, but no automation reads them today. CI does not enforce sync.