fix-codex-skill

修复无效的全局或项目技能格式，以兼容Codex，特别是通过`npx skills add`安装或从Claude专用模板复制的技能。当用户请求修复损坏的全局技能、无效的SKILL.md前言、缺少`agents/openai.yaml`文件、无法触发的技能、元数据模式问题，或跨Codex/Claude/代理技能文件夹的工具间技能兼容性问题时使用。

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