verify-skill-migration
starsforks
How to install verify-skill-migration?
zuharz/ccode-to-codex/verify-skill-migration
$npx -y skills add zuharz/ccode-to-codex --skill verify-skill-migrationValidator-backed migration QA for Codex skills and related docs
SKILL.md
| 1 | <!-- Generated by the ccode-to-codex mirror sync on 2026-04-14 from input revision 9a2403fb. --> |
| 2 | # Verify Skill Migration |
| 3 | |
| 4 | Use the canonical migration validator after each batch and before finalizing a migrated skill set. |
| 5 | |
| 6 | The validator implementation lives at: |
| 7 | |
| 8 | - `.codex/skills/verify-skill-migration/scripts/validate_skill_migration.py` |
| 9 | |
| 10 | Use the stable repo entrypoint for normal runs: |
| 11 | |
| 12 | ```bash |
| 13 | python3 tools/migration_support/validate_names.py |
| 14 | ``` |
| 15 | |
| 16 | ## Checks |
| 17 | |
| 18 | ### `structural-integrity` |
| 19 | |
| 20 | - Fails on MCP callable namespaces that still preserve hyphenated server IDs |
| 21 | |
| 22 | ### `frontmatter` |
| 23 | |
| 24 | - Applies to `SKILL.md` entrypoints only |
| 25 | - Parses YAML frontmatter |
| 26 | - Requires `name` and `description` |
| 27 | - Fails on prohibited keys: `allowed-tools`, `effort`, `metadata` |
| 28 | |
| 29 | ### `line-count` |
| 30 | |
| 31 | - Warns when a `SKILL.md` file reaches 500+ lines |
| 32 | - Warning only, not a failure |
| 33 | |
| 34 | ### `references` |
| 35 | |
| 36 | - Validates `references/` directories under the scan scope |
| 37 | - Fails on empty `references/` directories |
| 38 | - Fails on empty reference files, including nested files |
| 39 | |
| 40 | ### Cross-References Check |
| 41 | |
| 42 | - Warns on unknown skill references |
| 43 | - Uses discovered skill names instead of treating arbitrary backticked words as skills |
| 44 | |
| 45 | ### `skill-remnants` |
| 46 | |
| 47 | - Fails on legacy skill primitive call syntax in Codex artifacts |
| 48 | |
| 49 | ### `stale-paths` |
| 50 | |
| 51 | - Fails on operational legacy migration path references |
| 52 | - Ignores provenance banner lines such as `Source:` and `Generated by:` |
| 53 | |
| 54 | ### `operator-guidance` |
| 55 | |
| 56 | - Applies to the migration-family skill packages |
| 57 | - Fails on operator-facing repo paths that do not resolve there |
| 58 | - Fails on mistaken filesystem-root repo paths such as `/.codex/...` |
| 59 | - Fails on legacy slash-skill invocations in migration-family operational guidance |
| 60 | - Resolves skill-local `references/...` and `scripts/...` before repo-root paths |
| 61 | |
| 62 | ### `agent-dependencies` |
| 63 | |
| 64 | - Fails on unresolved named agent runtime dependencies |
| 65 | - Treats only `.codex/agents/*.toml` as authoritative runtime contracts |
| 66 | - Does not let legacy `.codex/agents/*.md` references satisfy dependency resolution |
| 67 | |
| 68 | ### `agent-flattening` |
| 69 | |
| 70 | - Warns when `spawn_agent(...)` appears to lose explicit `opus` / `sonnet` / `haiku` runtime intent |
| 71 | - Looks for nearby model-intent context without matching `model` or `reasoning_effort` overrides |
| 72 | |
| 73 | ### `agent-api-shape` |
| 74 | |
| 75 | - Warns on migrated-artifact examples that still use legacy positional `wait_agent(...)` call shapes |
| 76 | - Targets migration references and Tier 3 migrated skill artifacts without blocking unrelated older skills |
| 77 | |
| 78 | ### `executable-primitives` |
| 79 | |
| 80 | - Fails on Claude primitives in operational Codex guidance |
| 81 | - Ignores migration/comparison references and mapping-table contexts where primitive names are discussed, not executed |
| 82 | |
| 83 | ### `environment-readiness` |
| 84 | |
| 85 | - Inspects an explicit Codex home, defaulting to repo-local `.codex` |
| 86 | - Parses `config.toml` when present |
| 87 | - Warns on missing MCP commands by default because PATH is host-dependent |
| 88 | - Parses optional `hooks.json` and checks referenced hook commands/scripts |
| 89 | - Warns on oversized or legacy-reference-heavy `AGENTS.md` |
| 90 | - Validates plugin manifest JSON when plugin files exist |
| 91 | - Use `--strict-environment-readiness` when these host warnings should fail |
| 92 | |
| 93 | ## Usage |
| 94 | |
| 95 | Run the full validator during post-flight: |
| 96 | |
| 97 | ```bash |
| 98 | python3 tools/migration_support/validate_names.py |
| 99 | ``` |
| 100 | |
| 101 | Run a targeted scope: |
| 102 | |
| 103 | ```bash |
| 104 | python3 tools/migration_support/validate_names.py \ |
| 105 | --scan-dir .codex/skills/verify-skill-migration |
| 106 | ``` |
| 107 | |
| 108 | Run specific checks only: |
| 109 | |
| 110 | ```bash |
| 111 | python3 tools/migration_support/validate_names.py \ |
| 112 | --check frontmatter \ |
| 113 | --check cross-references \ |
| 114 | --check operator-guidance \ |
| 115 | --check agent-dependencies \ |
| 116 | --check agent-api-shape |
| 117 | ``` |
| 118 | |
| 119 | Run environment readiness against the repo-local Codex config: |
| 120 | |
| 121 | ```bash |
| 122 | python3 tools/migration_support/validate_names.py \ |
| 123 | --check environment-readiness \ |
| 124 | --codex-home .codex |
| 125 | ``` |
| 126 | |
| 127 | List available checks: |
| 128 | |
| 129 | ```bash |
| 130 | python3 tools/migration_support/validate_names.py --list-checks |
| 131 | ``` |
| 132 | |
| 133 | ## Result Semantics |
| 134 | |
| 135 | - `FAIL`: migration blockers or invalid Codex artifacts |
| 136 | - `WARN`: quality issues that should be reviewed but do not block execution |
| 137 | - `PASS`: no findings |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
