Skills Check

skills-check.yml is a hard gate that fails the build whenever a repository's vendored .claude/skills/ directory has drifted from the canonical claude-skills repo at its pinned version. It keeps every consuming repo's agent skills in lockstep with the shared source of truth.

Hard gate

This workflow is intended to fail the build on drift — it is not advisory. A red skills-check means the vendored skills no longer match canonical and must be re-synced before the PR can merge or main can build.

What it does

Each consuming repo vendors a copy of the shared skills under .claude/skills/. The canonical copy lives in the Skills wiki repository, <org>/claude-skills, pinned to a specific version. On every push to main and on every pull request, the gate runs the sync tool in check mode:

./.agent/skillsync --check

skillsync --check clones the canonical repo at the pinned version and compares it against the local .claude/skills/. If they differ, it exits non-zero and the job fails. To fix a failure, re-run the sync without --check locally and commit the result.

Installing the gate in a repo

Copy the workflow into each consuming repository as .github/workflows/skills-check.yml:

# Copy to each consuming repo as .github/workflows/skills-check.yml
# Hard gate: fails the build if vendored .claude/skills/ drifted from canonical@<pinned version>.
name: skills-check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # claude-skills is PRIVATE, so Actions needs read access to clone it.
      - run: git config --global url."https://x-access-token:${{ secrets.SKILLS_READ_TOKEN }}@github.com/".insteadOf "https://github.com/"

      - name: Verify skills are in sync with canonical
        run: ./.agent/skillsync --check

The repo must also vendor the ./.agent/skillsync tool and the .claude/skills/ directory it checks.

Private-repo clone auth

The canonical <org>/claude-skills repo is private, so the runner cannot clone it anonymously. Two pieces make the HTTPS clone work:

1. A read token. Create a repository secret named SKILLS_READ_TOKEN — a PAT or fine-grained token with contents: read on <org>/claude-skills. It needs read access to that one repo and nothing more.
2. A URL rewrite. The git config step rewrites every https://github.com/ clone URL to embed the token:

git config --global url."https://x-access-token:${{ secrets.SKILLS_READ_TOKEN }}@github.com/".insteadOf "https://github.com/"

With this in place, the HTTPS clone that skillsync performs under the hood authenticates transparently as x-access-token using the PAT, so the private canonical repo can be fetched.

Scope the token tightly

Use a fine-grained token limited to contents: read on <org>/claude-skills only. The rewrite applies to all github.com HTTPS clones in the job, so the token should grant the minimum needed. See the Secrets Matrix for where SKILLS_READ_TOKEN is registered.

Canonical source

The canonical skills live in the Skills wiki — the <org>/claude-skills repository — and consuming repos pin to a specific version of it. When the canonical skills are updated, bump the pin and re-run skillsync in each consumer to vendor the new version; the gate then passes against the new baseline. For how skills fit into the broader agent setup, see Agent Workflows.