Skip to content

Skill Sync Check (/skill-sync-check)

In plain terms

Checks that a project's skills are still in step with this shared library and offers to fix them if they've drifted apart.

What this skill does

Detect drift between the canonical skills in .claude/skills/ and the Gemini/Antigravity symlinks in .agent/workflows/, then propose and (after confirmation) run ./.agent/sync-skills.sh to repair it.

[!TIP] Run this after adding, removing, or renaming any skill — or any time you suspect Claude Code and Gemini/Antigravity have fallen out of sync.

Background

Skills have a single source of truth at .claude/skills/<name>/SKILL.md. Gemini/Antigravity reads .agent/workflows/<name>.md, which are symlinks (flat name.md → ../../.claude/skills/name/SKILL.md). The two directories must stay at 1:1 parity. ./.agent/sync-skills.sh repairs drift idempotently: it prunes broken links and creates links for new skills.

.agent/rules/ holds real (non-symlink) files — never touch them.

Trigger Conditions

  • Keywords: "check skill sync", "are skills in sync", "sync skills", "skill drift"
  • After any skill is added, removed, or renamed.

1. Detect drift (read-only)

Run this check from the repo root. It reports three kinds of drift without changing anything:

bash -euo pipefail <<'EOF'
cd "$(git rev-parse --show-toplevel)"
SKILLS_DIR=".claude/skills"
WF_DIR=".agent/workflows"

# Canonical skills = directories with a SKILL.md
skills=$(find "$SKILLS_DIR" -mindepth 1 -maxdepth 1 -type d \
  -exec test -f '{}/SKILL.md' \; -print | xargs -n1 basename 2>/dev/null | sort)

# Existing workflow links (strip .md)
links=$(find "$WF_DIR" -maxdepth 1 -name '*.md' 2>/dev/null \
  | xargs -n1 basename 2>/dev/null | sed 's/\.md$//' | sort)

echo "## Missing links (skill exists, no .agent/workflows entry):"
comm -23 <(echo "$skills") <(echo "$links") | sed 's/^/  - /' || true

echo "## Stale links (.agent/workflows entry with no matching skill):"
comm -13 <(echo "$skills") <(echo "$links") | sed 's/^/  - /' || true

echo "## Broken symlinks (target missing):"
find "$WF_DIR" -maxdepth 1 -type l ! -exec test -e '{}' \; -print | sed 's/^/  - /' || true

echo "## Non-symlink files in .agent/workflows (unexpected — should be symlinks):"
find "$WF_DIR" -maxdepth 1 -name '*.md' -type f -print | sed 's/^/  - /' || true
EOF

2. Decide

  • [ ] If all four sections are empty → report "✅ Skills are in sync — nothing to do." and stop.
  • [ ] If any drift is found → summarize it for the user and propose running ./.agent/sync-skills.sh. Note one caveat: the sync script only manages symlinks, so any real (non-symlink) .md files reported in the last section must be resolved by hand.

3. Confirm, then sync

  • [ ] Ask the user to confirm before running the script. Do not run it automatically.
  • [ ] On confirmation:
./.agent/sync-skills.sh
  • [ ] Report the script's added / pruned / total summary back to the user.

4. Verify

  • [ ] Re-run the detection block from step 1 to confirm all drift sections are now empty.
  • [ ] If .claude/skills/ or .agent/workflows/ changed, remind the user that the symlink changes are uncommitted and may need to be staged.