verify-skill-migration

name	verify-skill-migration
description	Validator-backed migration QA for Codex skills and related docs

Verify Skill Migration

Use the canonical migration validator after each batch and before finalizing a migrated skill set.

The validator implementation lives at:

• .codex/skills/verify-skill-migration/scripts/validate_skill_migration.py

Use the stable repo entrypoint for normal runs:

python3 tools/migration_support/validate_names.py

Checks

structural-integrity

• Fails on MCP callable namespaces that still preserve hyphenated server IDs

frontmatter

• Applies to SKILL.md entrypoints only
• Parses YAML frontmatter
• Requires name and description
• Fails on prohibited keys: allowed-tools, effort, metadata

line-count

• Warns when a SKILL.md file reaches 500+ lines
• Warning only, not a failure

references

• Validates references/ directories under the scan scope
• Fails on empty references/ directories
• Fails on empty reference files, including nested files

Cross-References Check

• Warns on unknown skill references
• Uses discovered skill names instead of treating arbitrary backticked words as skills

skill-remnants

• Fails on legacy skill primitive call syntax in Codex artifacts

stale-paths

• Fails on operational legacy migration path references
• Ignores provenance banner lines such as Source: and Generated by:

operator-guidance

• Applies to the migration-family skill packages
• Fails on operator-facing repo paths that do not resolve there
• Fails on mistaken filesystem-root repo paths such as /.codex/...
• Fails on legacy slash-skill invocations in migration-family operational guidance
• Resolves skill-local references/... and scripts/... before repo-root paths

agent-dependencies

• Fails on unresolved named agent runtime dependencies
• Treats only .codex/agents/*.toml as authoritative runtime contracts
• Does not let legacy .codex/agents/*.md references satisfy dependency resolution

agent-flattening

• Warns when spawn_agent(...) appears to lose explicit opus / sonnet / haiku runtime intent
• Looks for nearby model-intent context without matching model or reasoning_effort overrides

agent-api-shape

• Warns on migrated-artifact examples that still use legacy positional wait_agent(...) call shapes
• Targets migration references and Tier 3 migrated skill artifacts without blocking unrelated older skills

executable-primitives

• Fails on Claude primitives in operational Codex guidance
• Ignores migration/comparison references and mapping-table contexts where primitive names are discussed, not executed

environment-readiness

• Inspects an explicit Codex home, defaulting to repo-local .codex
• Parses config.toml when present
• Warns on missing MCP commands by default because PATH is host-dependent
• Parses optional hooks.json and checks referenced hook commands/scripts
• Warns on oversized or legacy-reference-heavy AGENTS.md
• Validates plugin manifest JSON when plugin files exist
• Use --strict-environment-readiness when these host warnings should fail

Usage

Run the full validator during post-flight:

python3 tools/migration_support/validate_names.py

Run a targeted scope:

python3 tools/migration_support/validate_names.py \
  --scan-dir .codex/skills/verify-skill-migration

Run specific checks only:

python3 tools/migration_support/validate_names.py \
  --check frontmatter \
  --check cross-references \
  --check operator-guidance \
  --check agent-dependencies \
  --check agent-api-shape

Run environment readiness against the repo-local Codex config:

python3 tools/migration_support/validate_names.py \
  --check environment-readiness \
  --codex-home .codex

List available checks:

python3 tools/migration_support/validate_names.py --list-checks

Result Semantics

• FAIL: migration blockers or invalid Codex artifacts
• WARN: quality issues that should be reviewed but do not block execution
• PASS: no findings