Fix Codex Skill

Use this skill to diagnose and repair skill-format problems across user-scope and project-scope skill directories.

What This Skill Fixes

• Invalid SKILL.md YAML frontmatter.
• Missing or invalid name / description fields.
• Non-Codex-compatible frontmatter keys.
• Missing agents/openai.yaml metadata for Codex UI/runtime.
• Description/type issues that break quick validation.

Scope Discovery

Run the repair script against default roots (user + project):

scripts/repair_codex_skill_format.py

Default user-scope roots:

• $CODEX_HOME/skills (if set)
• ~/.codex/skills
• ~/.claude/skills
• ~/.agents/skills

Default project-scope roots:

• <cwd>/.codex/skills
• <cwd>/.claude/skills
• <git-root>/.codex/skills (if different)
• <git-root>/.claude/skills (if different)

Safer First Run

Preview changes first:

scripts/repair_codex_skill_format.py --dry-run

Then apply:

scripts/repair_codex_skill_format.py

Useful Flags

• Add extra scan roots:

scripts/repair_codex_skill_format.py --root /path/to/skills --root /another/skills

• Scan only user-scope defaults:

scripts/repair_codex_skill_format.py --no-project

• Scan only project-scope defaults:

scripts/repair_codex_skill_format.py --no-user

• Verbose output:

scripts/repair_codex_skill_format.py --verbose

Validation Step

After repair, validate critical skills:

python3 /Users/khang/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-dir>

For format rules and rationale, load:

• references/codex-format-rules.md
• references/scope-discovery.md
• references/remediation-workflow.md