skill-sync-check.yml

name: Skill Sync Check

on:
  pull_request:
    paths:
      - "examples/**/*.md"
      - "AGENTS.md"
      - "ACCESSIBILITY.md"
  push:
    branches: [main]
    paths:
      - "examples/**/*.md"
      - "AGENTS.md"
      - "ACCESSIBILITY.md"
  workflow_dispatch:

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  check-skill-drift:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install yq
        run: |
          sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
          sudo chmod +x /usr/local/bin/yq

      - name: Check for stale skills
        id: check
        run: |
          STALE=()
          for sync_file in skills/*/SYNC.md; do
            skill_dir=$(dirname "$sync_file")
            skill_name=$(basename "$skill_dir")

            # Extract canonical_source and last_synced_commit using yq on the embedded YAML block
            # The YAML block is inside a fenced code block in the Markdown; extract it first
            yaml_block=$(awk '/^```yaml/{found=1; next} /^```/{found=0} found' "$sync_file")
            if [ -z "$yaml_block" ]; then
              continue
            fi

            source_file=$(echo "$yaml_block" | yq '.canonical_source' -)
            synced_sha=$(echo "$yaml_block" | yq '.last_synced_commit' -)

            # Treat null or empty string as unset
            [ "$source_file" = "null" ] && source_file=""
            [ "$synced_sha" = "null" ] && synced_sha=""

            if [ -z "$source_file" ]; then
              continue
            fi

            # Skip if source file doesn't exist
            if [ ! -f "$source_file" ]; then
              continue
            fi

            # Get the latest commit SHA for the source file
            current_sha=$(git log -1 --format="%H" -- "$source_file")

            # Flag as stale if SHA differs or was never synced
            if [ "$synced_sha" != "$current_sha" ]; then
              echo "STALE: $skill_name (source: $source_file, synced: ${synced_sha:-<never>}, current: $current_sha)"
              STALE+=("$skill_name ($source_file)")
            fi
          done

          if [ ${#STALE[@]} -gt 0 ]; then
            echo "stale_skills=$(IFS=';'; echo "${STALE[*]}")" >> "$GITHUB_OUTPUT"
            echo "has_stale=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_stale=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Comment on PR (if stale skills found)
        if: github.event_name == 'pull_request' && steps.check.outputs.has_stale == 'true'
        uses: actions/github-script@v7
        with:
          script: |
            const staleList = process.env.STALE_SKILLS.split(';').map(s => `- \`${s.trim()}\``).join('\n');
            const body = `## ⚠️ Skill Sync Check

            One or more AI agent skills may be out of sync with their source \`examples/\` file:

            ${staleList}

            **What to do:**
            1. Review the diff between the current \`examples/\` file and the skill's \`SKILL.md\`
            2. Update \`SKILL.md\` to reflect any new requirements or changed patterns
            3. Set \`last_synced_commit\` in the skill's \`SYNC.md\` to the current commit SHA
            4. Rebuild the archive: \`cd skills && zip -r <skill-name>.skill <skill-name>/\`

            See [skills/README.md](https://github.com/mgifford/ACCESSIBILITY.md/blob/main/skills/README.md) for full instructions.`;

            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body
            });
        env:
          STALE_SKILLS: ${{ steps.check.outputs.stale_skills }}

      - name: Open issue on push to main (if stale skills found)
        if: github.event_name == 'push' && steps.check.outputs.has_stale == 'true'
        uses: actions/github-script@v7
        with:
          script: |
            const staleList = process.env.STALE_SKILLS.split(';').map(s => `- \`${s.trim()}\``).join('\n');
            const title = '⚠️ Skill sync drift detected';
            const body = `## Stale AI Agent Skills

            The following skills may be out of sync after a recent change to \`examples/\`:

            ${staleList}

            **What to do:**
            1. Review the diff between each updated \`examples/\` file and its skill's \`SKILL.md\`
            2. Update \`SKILL.md\` to reflect new requirements or changed patterns
            3. Set \`last_synced_commit\` in \`SYNC.md\` to the current commit SHA
            4. Rebuild the archive: \`cd skills && zip -r <skill-name>.skill <skill-name>/\`

            See [skills/README.md](https://github.com/mgifford/ACCESSIBILITY.md/blob/main/skills/README.md) for full instructions.

            _This issue was opened automatically by the skill-sync-check workflow._`;

            // Check for an existing open issue with the same title to avoid duplicates
            const existing = await github.rest.issues.listForRepo({
              owner: context.repo.owner,
              repo: context.repo.repo,
              state: 'open',
              labels: 'skill-sync'
            });

            const duplicate = existing.data.find(i => i.title === title);
            if (duplicate) {
              await github.rest.issues.update({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: duplicate.number,
                body
              });
              console.log(`Updated existing issue #${duplicate.number}`);
            } else {
              const created = await github.rest.issues.create({
                owner: context.repo.owner,
                repo: context.repo.repo,
                title,
                body,
                labels: ['skill-sync']
              });
              console.log(`Created issue #${created.data.number}`);
            }
        env:
          STALE_SKILLS: ${{ steps.check.outputs.stale_skills }}