Skill Drift Scanner

Skill Drift Scanner

Inspect whether the machine's active Codex and Claude skills match the intended source-of-truth set, whether the autosync timers are healthy, and whether either tool needs a reload or restart to pick up changes.

When to use

• "Are my skills installed?"
• "Are all skills synced?"
• "Did autosync run?"
• "What changed in my skills?"
• "Do I have skill drift?"
• "Give me a skills health report"

Scope

This skill audits a machine-level skill deployment, not a single application repo.

Typical install layout:

• source skills repo clone or mirror
• optional local overlay skills
• Codex user skills at ~/.codex/skills
• agent-compatible user skills at ~/.agents/skills
• Claude user skills at ~/.claude/skills
• repo-local project skill pairs at .claude/skills and .agents/skills
• state and reports under a local state directory

It checks:

1. Missing installed skills
2. Content drift between source and installed copies
3. Unmanaged custom skills in either install root
4. Repo-local project skills that exist for Claude but not Codex-compatible agents, or the reverse
5. Scheduler health for sync/report timers
6. Whether the last sync changed skill content, which implies Codex may need restart while Claude may only need reload or a fresh skill scan

Workflow

Step 1 — Locate the scanner

Use the environment's installed scanner command; do not assume a Linux/root home path. Prefer an explicit override, then PATH, then the user's local bin:

scanner="${CODEX_SKILL_SYNC:-$(command -v codex-skill-sync || true)}"
[ -n "$scanner" ] || scanner="$HOME/.local/bin/codex-skill-sync"

Step 2 — Run the status command

If the scanner exists:

"$scanner" status

This should print the current report without mutating anything. If a text report is produced, summarize it with:

python3 scripts/parse_status_report.py <report-path-or->

If codex-skill-sync is not installed but the current repo has sync-skills.sh, use this non-mutating fallback:

sh sync-skills.sh --all --dry-run

Treat this as a source-to-installed-copy dry-run, not a full scheduler/autosync health report. To summarize the fallback output, run:

sh sync-skills.sh --all --dry-run | python3 scripts/parse_status_report.py --sync-dry-run -

Step 3 — If the user wants reconciliation, run sync

Use the same resolved scanner path:

"$scanner" sync

If the scanner is unavailable and this repo's fallback is appropriate:

sh sync-skills.sh --all

Use this when the user wants the machine brought back to source of truth, not just inspected.

Step 4 — Interpret results by tool

• Missing Installed Skills means the source repo has a skill that an install root does not.
• Content Drift means the skill exists in both places but file content differs.
• Unmanaged Custom Skills means there are extra custom skills under an install root that the autosync subsystem does not own.
• Project Skill Parity means each real repo's .claude/skills/<name> and .agents/skills/<name> copies are paired. Missing one side can be reconciled automatically; same-name content conflicts are reported for manual review.
• Codex restart recommended after last change: yes means a background sync changed installed content and open Codex sessions may still have stale skill state.
• Claude can hot-reload in some setups, but do not claim reload success unless verified on the installed Claude version.

Output contract

Return:

1. The top-line status in one sentence
2. The highest-signal per-tool sections from the report
3. The Project Skill Parity section if it reports any missing or drifted repo-local skills
4. The exact reconcile command if drift exists, using the resolved scanner path from Step 1

If the user asks for the full report, point them to the local report path the scanner prints or to the state/report directory for that environment.

Skill Maintenance

When editing parser expectations, run:

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest tests/test_parse_status_report.py

Fixtures cover text status parsing, fallback dry-run parsing, live command resolution, and scheduler-health report shape.

What this skill does NOT do

• It does not push changes to GitHub.
• It does not assume every tool hot-reloads skills the same way.
• It does not delete unmanaged custom skills unless the user explicitly asks.