企业官网建设流程全解析

Skills Catalog for Codex 日志排查：4 个场景 5 分钟定位技能异常

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

Skills Catalog for Codex 为 Codex AI 助手提供一组可复用的 Agent Skills（技能包），让你以可重复的方式完成特定任务。当技能装不上、没响应或报错时，本文带你在 4 个真实场景里做技能日志排查：先看哪里、读什么、怎么修。

先理清布局：日志信息其实分散在 3 个地方

先说清楚一个事实：📂 本仓库没有直接提供任何日志文件，clone 下来找不到.log文件。那技能出问题时，"日志"在哪？通常是这 3 处：

1. Codex 会话输出：你在 Codex 里执行$skill-installer时的命令回显和错误提示
2. 脚本运行输出：技能scripts/目录下 Python 脚本的标准输出与报错信息
3. 安装目录本身：技能实际落在$CODEX_HOME/skills/（默认~/.codex/skills），文件是否完整就是最直接的"运行日志"

记住这 3 处，后面所有场景都从这 3 处切入。

30 秒上手：用 list-skills 脚本查看技能状态

安装和查询技能的逻辑都写在 skills/.system/skill-installer/ 这个内置技能里。最常用的一条命令是列出可安装技能：

python3 skills/.system/skill-installer/scripts/list-skills.py

怎么读输出：

• 正常：打印Skills from openai/skills:开头的清单，已装技能带(already installed)标注
• 异常信号：网络错误或 API 不可用提示（该脚本通过 GitHub API 拉取清单，需要联网；在 Codex 沙箱内运行时还需要授权升级）

需要机器可读格式时，追加--format json参数，方便你用脚本进一步过滤。

场景一：执行 $skill-installer 后，技能没装上

你会遇到什么现象：输入$skill-installer gh-address-comments后，没有出现预期成功提示，或直接报错退出。

去哪里看：Codex 会话里这条命令的完整输出，以及安装目录~/.codex/skills/<技能名>/。

怎么读输出：

• 成功时，技能会被复制进$CODEX_HOME/skills/<技能名>，提示下一轮对话即可使用
• 安装脚本在目标目录已存在时会直接中止，不会覆盖——如果你之前装过同名技能，报错往往就卡在这一步
• 涉及网络的下载失败（认证、权限类错误），脚本会尝试回退到 git sparse checkout，HTTPS 失败再试 SSH

怎么处理：

1. 检查~/.codex/skills/下是否已有同名目录；有则是"已存在"中止，先处理旧目录再重装
2. 网络类报错先确认能正常访问外网，私仓场景检查 git 凭据
3. 装完后重启 Codex（见场景二，这是新手最常漏的一步）

场景二：装好了，Codex 里却"看不见"这个技能

你会遇到什么现象：安装成功、也重启过 Codex，但用技能名调用时没反应，或者被当成普通聊天处理。

去哪里看：安装目录~/.codex/skills/<技能名>/的文件列表。

怎么读：每个技能目录的入口是SKILL.md，文件头部的name字段就是 Codex 匹配技能用的名字。两个典型异常：

• 目录存在但没有SKILL.md——说明下载不完整，技能不会被加载
• 目录名和你调用的名字不一致——Codex 按名字匹配，对不上就当没装

怎么处理：

1. 确认安装后重启了 Codex（README 明确要求重启才能加载新技能）
2. 用上面 30 秒上手的list-skills.py核对技能名拼写
3. 缺SKILL.md就删掉该技能目录重装

场景三：运行技能时报错输出

你会遇到什么现象：技能本身能唤起，但执行过程中抛出异常，比如带脚本的技能跑一半失败。

去哪里看：脚本的报错输出，重点看 traceback 的最后几行（真正的异常类型和位置）。

怎么读：

• ModuleNotFoundError一类——环境缺依赖，与技能逻辑无关
• 网络/权限错误——脚本要访问外部服务（如 skills/.curated/gh-address-comments/scripts/ 里的fetch_comments.py需要拉取 GitHub 数据）
• 参数错误——对照该技能的SKILL.md，前置条件和参数可能和你给的不一致

怎么处理：

1. 脱离 Codex，在终端里手动跑一遍脚本，拿到完整报错
2. 按异常类型补依赖或修网络
3. 仍无解时，打开该技能的SKILL.md逐条核对使用说明

场景四：升级或重启 Codex 后，原本正常的技能失效

你会遇到什么现象：技能昨天还好用，升级 Codex 或换机器后突然报错或不被识别。

去哪里看：仓库根目录的 README.md 顶部的deprecation（弃用）声明。

怎么读：这份目录已被标记为弃用，官方建议迁移到 OpenAI 的新插件仓库。也就是说，随着 Codex 版本推进，本目录里的技能格式或依赖可能与新版 Codex 逐渐不兼容——这类"莫名失效"很多不是你的操作问题。

怎么处理：

1. 先确认问题是否只在特定技能上出现：只挂一个技能，多半是它本身过时
2. 批量失效则按官方声明的思路，用新版仓库里的技能示例替换
3. 迁移期间保留旧版本技能做对照，方便二分定位

深入排查：顺着目录结构锁定问题源头

疑难问题时，按这个顺序翻目录：

• skills/.system/：5 个随最新版 Codex 自动安装的内置技能（imagegen、openai-docs、plugin-creator、skill-creator、skill-installer），不要手动重装，出问题先看版本
• skills/.curated/：40 个精选技能，每个独立成目录
• 单个技能内部结构基本一致：SKILL.md（入口说明，必读）→scripts/（可执行脚本，报错高发区）→agents/、references/（行为与参考配置）→LICENSE.txt

排查口诀：🔍 先读SKILL.md确认预期行为，再看scripts/对应脚本的报错，最后核对agents/下的配置文件是否与环境匹配。涉及安全漏洞或模型输出异常，可通过 contributing.md 里给出的官方安全渠道反馈。

下次报错时的行动清单

1. 先问"日志在哪"：会话输出 → 脚本输出 → 安装目录，三处依次看，别跳
2. 装不上：查~/.codex/skills/<技能名>/是否已存在、网络是否正常
3. 看不见：确认重启了 Codex、SKILL.md存在、名字拼写一致
4. 跑报错：手动复跑脚本，只看 traceback 最后几行定位异常类型
5. 升级后批量失效：先读 README 的弃用声明，按官方建议迁移技能来源

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills