Codex Skills 使用记录：安装、规划、文档处理与 CI 排错
用 Codex 写代码，反复出现的要求往往很相似：先看项目再给计划、出错先查根因、生成文档后检查排版、CI 红了先看日志。Skills 可以把这些工作方法保存下来，减少重复沟通。
这篇整理五组工具的安装入口、作用、使用方式与验收方法。先说一个容易混淆的地方：它们并不都是同一种东西，SuperClaude 也不能直接当成 Codex 的原生技能使用。
核对日期：2026-11-02。本文是安装与使用方法整理，提示词均为示例，不代表所有命令都已在本机实测成功。安装时以所链接项目的当前说明为准。
一、先分清工具的定位
| 名称 | 类型 | 解决的问题 |
|---|---|---|
| create-plan | 单个 skill | 先阅读项目，再输出简短行动计划 |
| Superpowers | 开发流程技能集合及插件 | 组织设计、实现、测试和审查 |
| Document Skills | 文档技能集合 | 处理 PDF、Word、Excel、PPT |
| gh-fix-ci | 单个 skill | 定位 GitHub Actions 的 PR 检查失败 |
| SuperClaude Framework | Claude Code 配置框架 | 通过命令、角色和模式组织开发 |
Skill 一般以 SKILL.md 为入口，还可以附带脚本、参考资料和模板。模型先看到名称和简介，匹配任务后读取详细指令；用户也能显式指定技能。它提供工作方法，实际操作仍需要工具、依赖与权限。OpenAI：Build skills
对话指令与终端命令要分开
下面应输入 Codex 对话框：
$skill-installer install gh-fix-ci$skill-installer 是技能调用写法，不是 shell 程序。直接粘进终端，shell 会尝试展开变量。下面才是终端命令：
git clone https://github.com/anthropics/skills.git ~/.agents/skills/anthropic-skills安装器通常把技能放到 ~/.codex/skills；手动安装还会遇到用户级 ~/.agents/skills 或项目级 .agents/skills。不同入口不要混为一谈，应检查实际加载路径。安装后可以在下一轮对话检查是否可用，界面仍未刷新时再重新打开会话。
二、create-plan：先把任务变成计划
能起什么作用
本机安装的 create-plan 会先阅读 README 和相关代码，明确范围，生成有顺序的行动清单，并包括验证与风险项。它要求规划期间只读，不修改文件。
适合需求基本清楚、涉及多个文件、需要先评估影响面的任务。只改一个错别字时，通常无需额外规划。
安装：先核对当前来源
常见教程是在 Codex 对话框输入：
$skill-installer install create-plan这里需要补充时效性：本次核对时，OpenAI skills 仓库中 .curated/create-plan 和 .experimental/create-plan 的历史文件路径均返回 404。本机已安装，不代表新环境还能照旧安装。
更稳妥的方式是先问：
$skill-installer 列出当前可安装的技能，检查是否有 create-plan。
如果没有，说明查询结果，不要安装来源不明的同名替代品。官方安装器支持从列表或指定 GitHub 路径安装；列表中没有时，需要核对新位置。也可以直接请求 Codex 制定计划，基本任务并不依赖这个技能名称。OpenAI skills 仓库
LobeHub 可以用于发现技能，但搜索结果不等于官方版本，应进一步检查维护者、源仓库和具体的 SKILL.md。
怎么使用
在已经安装的环境中输入：
使用 create-plan，为订单列表增加按状态筛选制定计划。
先阅读现有接口、查询代码和测试，只输出计划。
列出涉及文件、边界情况和验证命令，本轮不要修改代码。验收计划时看三点：改哪里、保留哪些行为、怎样证明改动正确。如果只有“分析需求、开发、测试、上线”，还需要继续具体化。
确认计划后，再发实现请求。不要同时要求“只规划”和“顺便全部实现”。
三、Superpowers：把开发过程组织起来
当前推荐的安装入口
当前上游 README 推荐通过插件市场安装：
- Codex App：侧栏打开 Plugins，查找 Superpowers 并安装。
- Codex CLI：输入
/plugins，搜索 Superpowers，选择安装。
入口以客户端当前版本为准。Superpowers 安装说明
旧教程常见：
git clone https://github.com/obra/superpowers.git ~/.agents/skills/superpowers这可以下载仓库，但下载完成不等于正确接入宿主。当前版本优先遵循上游 Codex 安装说明，不再把这一行作为所有版本通用的完整安装流程。
另外两条路线：
npx @supercorks/skills-installer install
skill-install -t codex install https://github.com/obra/superpowers/archive/main.zip它们依赖第三方安装器，本次未验证与当前版本的兼容性，不作为推荐步骤。已经装过手动版本时，再装插件前应检查是否重复加载同一套技能。
能起什么作用
Superpowers 将开发组织为需求澄清、设计、规划、实现、测试与审查等阶段。它强调测试驱动与按计划推进，复杂任务更有条理，简单任务则可能增加沟通轮次。具体触发流程会随版本变化。Superpowers 工作流
怎么使用
使用 Superpowers 的相关开发技能，给博客增加标签筛选。
先阅读现有页面和内容集合，说明方案和影响范围。
保留现有视觉样式，不引入新框架。
实现后运行项目已有构建命令，并检查没有匹配文章的情况。排查缺陷时，把问题收窄：
使用 systematic-debugging 排查：
文章详情页正常，标签页却漏掉同一篇文章。
先追踪数据和筛选条件，给出复现与根因证据，再提出最小修改。这些是提示词示例，不是已经完成的实测案例。实际使用时应补上复现步骤、期望行为和错误输出。验收看相关文件、修改原因和验证结果，而不只是它有没有说“正在使用技能”。
四、Document Skills：按文件类型选技能
先修正目录
Anthropic 仓库中，文档技能分别位于：
skills/pdf
skills/docx
skills/xlsx
skills/pptxdocument-skills 是 Claude Code 中的插件分组名，不应据此推导出 skills/document-skills 目录。Anthropic skills README
在 Codex 中安装
可以让安装器按需安装：
$skill-installer 从 anthropics/skills 安装以下路径：
skills/pdf
skills/docx
skills/xlsx
skills/pptx
如果已经安装，报告现有位置，不要覆盖。想手动查看源码，也可以克隆：
git clone https://github.com/anthropics/skills.git ~/.agents/skills/anthropic-skills随后检查具体技能是否已被当前 Codex 发现。建议只选择一种管理方式，避免同一技能既由安装器安装，又从克隆目录重复加载。
这些技能原本面向 Claude 环境。在 Codex 本地使用时，应检查脚本路径、Python/Node 包和渲染工具；说明里写“预装”，不代表自己的电脑也已安装。文档技能还有各自的许可，分发前应查看对应的 LICENSE.txt。
能起什么作用
| 技能 | 典型任务 | 验收重点 |
|---|---|---|
| 文本和表格提取、合并拆分、表单、OCR | 页码、字段对应、扫描件识别 | |
| docx | 创建或修改 Word、结构与样式处理 | 分页、表格宽度、标题层级 |
| xlsx | 清洗数据、公式、格式化工作簿 | 公式错误、结果、数据类型 |
| pptx | 创建修改演示文稿、读取页面内容 | 溢出、遮挡、字体与一致性 |
具体能力见 PDF、Word、Excel 和 PPT 说明。
怎么使用
使用 pdf，提取 inputs/report.pdf 中的表格到 outputs/report.csv。
保留原页码，无法识别的字段标为待核对，不要猜测。使用 docx，把 inputs/notes.md 整理为 outputs/部署手册.docx。
使用标题层级和自动编号，命令保持等宽字体。
生成后渲染检查分页与表格，报告无法完成的检查。使用 xlsx，清洗 inputs/orders.xlsx 的订单数据。
按支付时间所在月份汇总收入，排除退款订单，汇总保留公式。
另存为 outputs/orders-summary.xlsx，检查公式错误和金额口径。使用 pptx，把 inputs/outline.md 制作为 8 页技术分享。
听众是 Java 后端工程师，每页一个重点。
输出 outputs/share.pptx，检查每页是否有溢出或遮挡。文件任务至少要交代输入、输出、保留内容和验收要求。“帮我处理这个表”会留下大量口径选择；明确日期字段、退款处理方式和计算规则，结果才容易核对。
五、gh-fix-ci：先看日志，再修 CI
安装与前置条件
在 Codex 对话框输入：
$skill-installer install gh-fix-ci还需要 GitHub CLI。下面以 macOS 且已安装 Homebrew 为例，已有 gh 时跳过第一行：
brew install gh
gh auth login
gh auth status账号必须能访问仓库和 Actions 日志，技能不会绕过权限。
能起什么作用
它通过 gh 定位 PR 失败检查、读取 GitHub Actions 日志、总结失败原因并提出计划。官方技能要求获得明确批准后实施；Buildkite 等外部检查默认只报告详情链接。gh-fix-ci 官方说明
怎么使用
在目标仓库会话中输入：
使用 gh-fix-ci 排查 PR #123 的失败检查。
先报告检查名称、日志链接、失败片段和修复计划。
本轮不要修改代码，等我确认后实施。确认后继续：
按刚才的计划修复，只修改相关文件。
运行对应测试，分别说明本地验证结果与远端 Actions 状态。本地测试通过，与推送后远端 CI 通过，是两个验收项。后者还需要触发工作流并等待结束，不能用本地结果代替。遇到网络等偶发环境错误，也应先判断原因，不能为“变绿”删除测试或跳过检查。
LobeHub 和 Community Registry 可以用于发现技能，但同名条目可能来自其他维护者。第三方命令 npx @bbhxwl/skills install gh-fix-ci --target codex 本次未实测；这里优先使用 OpenAI 仓库来源。
六、SuperClaude Framework：先确认宿主
SuperClaude 是面向 Claude Code 的社区配置框架，并非 Anthropic 官方产品。它提供命令、角色与工作模式，不能因为也使用 Markdown 指令，就假定整套框架能直接在 Codex 运行。SuperClaude 项目
安装与使用：以下属于 Claude Code 路线
当前 README 的 pipx 安装方式如下，需要先具备 pipx：
pipx install superclaude
superclaude install然后在 Claude Code 中使用该版本支持的命令，例如：
/sc:analyze src命令集合随版本变化，以当前 README 和命令参考为准。这些不是 Codex 终端命令，也不能假定 Codex 对话框识别它们。SuperClaude 安装说明
在 Codex 中应该怎么借鉴
如果只用 Codex，我会先用规划、调试和具体任务技能覆盖需求。确实需要某个独立技能时，再核对其宿主要求、脚本和依赖，单独适配，而不是先装整个框架。
可以先让 Codex 做只读检查：
阅读这份 SuperClaude 技能说明，检查是否依赖 Claude Code 的
命令、工具名、目录或运行时。列出在 Codex 中需要调整的地方，
先不要安装整个框架，也不要修改配置。参考工作方法与原样运行框架，是两种不同的工作量，先确定自己需要哪一种。
七、我会怎样组合使用
不必每次把五套工具全部叫一遍，按当前任务选择即可：
| 当前任务 | 优先选择 | 交付物 |
|---|---|---|
| 需求清楚，先评估怎么改 | create-plan 或直接请求计划 | 范围、步骤与验证 |
| 新功能涉及多处修改 | Superpowers | 设计、实现与验证证据 |
| 已有可复现缺陷 | 调试类技能 | 根因、最小修改与回归结果 |
| 处理办公文件 | 对应文档技能 | 可打开且内容正确的文件 |
| GitHub Actions 失败 | gh-fix-ci | 日志、计划与复查结果 |
| 学习 Claude Code 框架 | 单独研究 SuperClaude | 宿主适配结论 |
给技能的提示词，可以复用这个结构：
使用 [技能名称] 处理 [任务]。
输入/项目位置：[路径或 PR]。
期望结果：[具体行为或输出文件]。
限制：[不改哪些内容、是否允许增加依赖]。
验证：[运行什么检查、如何判定正确]。安装后没生效，先检查什么
- 当前会话可用技能列表有没有它，实际路径下有没有 SKILL.md。
- 任务描述是否符合技能负责的范围。
- 是否有同名版本，或者装在另一套工具的目录下。
- 脚本、依赖与权限是否可用，失败信息有没有被报告。
- 安装后是否已进入下一轮对话，必要时重新打开会话。
也可以直接问 Codex：“本次使用了哪个技能，读取路径是什么，执行了哪些检查，还有什么未完成？”这比根据输出风格猜测更容易核对。
Skills 最有用的地方，是把反复强调的要求变成可重复执行的流程。先选一个常见任务，明确输入与验收，观察它是否减少了重复沟通，再扩展到其他技能。