Agent Skill Sync

Canonical Location

.claude/skills/ is the canonical source of truth for all agent skill definitions.

All edits go here. Never edit .codex/skills/ directly.

Mirror Location

.codex/skills/ is the repo-local mirror for Codex compatibility.

The contents of .codex/skills/ are generated from .claude/skills/ by the sync script. They will be overwritten on the next sync run.

Sync Workflow

After editing any .claude/skills/<skill>/SKILL.md:

python scripts/sync_agent_skills.py

This copies all skill files from .claude/skills/ to .codex/skills/, creating destination folders as needed and overwriting any existing files.

To preview changes without writing:

python scripts/sync_agent_skills.py --dry-run

Validation

Run the validation script to confirm both locations are in sync and all expected skills are present:

python scripts/validate_agent_skills.py

The validator checks:
- Each expected skill has a SKILL.md in .claude/skills/<skill>/
- Each SKILL.md has valid YAML frontmatter with name: and description: fields
- Each expected skill has a SKILL.md in .codex/skills/<skill>/
- docs/agent-skill-sync.md exists and references sync_agent_skills.py
- AGENTS.MD references .claude/skills/ and the sync rule

Codex User-Level Install Path

For user-level Codex skill installation (outside this repo):

• Linux/macOS: ${CODEX_HOME:-$HOME/.codex}/skills
• Windows: $env:CODEX_HOME\skills or $HOME\.codex\skills

Copy individual skill directories from .codex/skills/<skill>/ to the user-level path to make skills available globally in Codex.

Do Not Let the Two Copies Drift

If .claude/skills/ and .codex/skills/ diverge, the validation script will fail. Keep them in sync by running python scripts/sync_agent_skills.py after every edit to a skill file.

Available Skills

Skill	Trigger
weekly-round	Weekly NRL round scrape and refresh pipeline
dbt-dq	dbt build and data quality checks
bucket-stage-debug	Staging errors, missing data, bucket connectivity
model-edge-review	Edge identification and model performance review
odds-movement-monitor	Odds snapshots, CLV updates, movement detection
streamlit-app-check	Launch and validate the bet advisor app
weather-refresh	Ingest weather data and validate venue coverage
security-check	Review for secrets and sensitive files before committing