gh-fix-ci

gh-fix-ci 技能概览

gh-fix-ci 是一项专门面向 GitHub Actions 故障排查的技能，适用于在可访问 gh 的仓库中排查失败的 PR 检查。它可以帮你查看失败的 check，提取最相关的日志片段，总结出问题出在哪里，并在任何代码变更前先准备修复方案。

这项技能最适合维护者和代理在 GitHub 托管的 workflow 上做 gh-fix-ci for CI Troubleshooting，尤其是在失败信号很嘈杂、你需要快速从红色 check 走到可执行诊断的时候。对于 Buildkite 这类外部 CI 提供商，它的价值就小得多，因为技能明确把这些场景排除在范围之外，只会给出 details URL。

gh-fix-ci 擅长什么

当问题出在 GitHub Actions 日志里，而且你需要的是结构化排查流程，而不是一个泛泛的“帮我修 build”提示词时，gh-fix-ci 最能发挥作用。它依赖已认证的 gh 访问，先定位 PR，再检查 checks，并把失败范围收敛到最值得优先阅读的那一部分。

gh-fix-ci 适合放在什么位置

当你的主要任务是判断为什么某个 PR check 失败，而不是重构仓库的 CI 系统时，就该用 gh-fix-ci。如果你想要的是一个可重复的流程：先基于证据定位问题，再输出简洁的修复方案，最后在批准后才实施改动，那么它非常合适。

需要先知道的主要限制

这项技能依赖 GitHub CLI 访问权限，以及 repo / workflow 的作用域。如果 gh auth status 还没有通过，流程会尽早停下，先让你完成认证，再开始任何分析。

如何使用 gh-fix-ci 技能

安装并验证访问权限

进行 gh-fix-ci install 时，使用下面的命令把技能加入你的 skills 集合：

npx skills add openai/skills --skill gh-fix-ci

在使用之前，先确认 gh 在目标仓库里可用：

gh auth status

如有需要，使用正确的 repo 和 workflow scopes 执行 gh auth login，然后重试。没有这项访问权限，技能就无法检查 checks 或拉取日志。

先给出正确的输入

高质量的 gh-fix-ci usage 一开始就应该包含仓库路径，以及 PR 编号、PR URL，或者当前分支对应的 PR。一个好的提示词可以是：

“Use gh-fix-ci on this repo, inspect PR 184, summarize the failing GitHub Actions job, and propose the smallest fix plan before editing.”

这比“CI 坏了”更有效，因为它给了技能明确的目标、范围边界，以及一个先审批后改动的闸门。

先读这些文件

如果你想快速看一份 gh-fix-ci guide，先检查 SKILL.md，再看 scripts/inspect_pr_checks.py、agents/openai.yaml 和 LICENSE.txt。这些文件会展示预期工作流、支持的快速启动路径、默认 prompt，以及这个仓库的运行方式。

如果你想理解执行细节，scripts/inspect_pr_checks.py 尤其有用，因为它会揭示失败 checks 是如何收集的、日志片段如何筛选、以及脚本认定什么才算相关失败。

在实际工作流中使用它

一个实用的顺序是：先认证，解析 PR，检查 checks，提取失败日志上下文，总结根因，然后在实施修复前先请求批准。如果你的环境里有类似 create-plan 这样的计划型技能，就直接用；否则，要求输出一个简洁的内联计划即可。

为了获得更好的结果，请提供：

• repo 路径
• PR 编号或 URL
• 你是只要诊断，还是诊断加修复
• 任何已知的噪声 job、易抖动的 checks，或需要忽略的外部提供商

gh-fix-ci 技能常见问题

gh-fix-ci 只适用于 GitHub Actions 吗？

是的，主要就是这样。它的设计目标是借助 gh 调试运行在 GitHub Actions 上的失败 checks。如果失败来自外部提供商，这项技能不会深入分析那个系统，而是只应把你指向 details URL。

如果我自己能写 prompt，还需要 gh-fix-ci 吗？

你当然可以临时写一个 prompt，但 gh-fix-ci skill 提供的是可重复的工作流：认证、解析 PR、检查 checks、总结失败片段，并在改动前暂停。这样的结构能减少猜测，比那种笼统的调试提示更可靠。

gh-fix-ci 适合新手吗？

适合，只要用户能识别仓库和 PR。技能会处理 CI 排查流程，但新手仍然需要有效的 gh 认证，以及愿意提供明确 PR 目标。

什么时候不该用 gh-fix-ci？

当问题显然不在 GitHub Actions 内、你没有 gh 访问权限，或者你只需要做一份宽泛的 CI 架构评审时，就不该用它。它优化的是失败的 PR checks，而不是通用的 DevOps 建议。

如何改进 gh-fix-ci 技能

给技能一个更精准的目标

提升效果最大的方式，就是把 repo、PR 和症状说清楚。“PR 92 在依赖更新后 test 失败了”要比“修 CI”好得多，因为它能帮助 gh-fix-ci 聚焦到正确的 job，并过滤出正确的日志片段。

说明你想要什么输出

如果你只想让技能停留在分析阶段，就明确说出来。如果你希望先给修复计划、并且只有在批准后才改代码，也要直接说明。这个技能本身就是围绕“诊断 + 计划”构建的，明确指令可以减少它越界输出。

补充会影响排查的 CI 上下文

提到 runner、workflow 名称、历史上是否易抖动，或者是否涉及外部系统。之所以重要，是因为 gh-fix-ci 最擅长做的，就是把可行动的 GitHub Actions 失败和无关噪声、以及范围外的提供商区分开来。

基于日志证据迭代，不要靠猜

如果第一轮只给出了部分诊断，把确切失败的 job 名称、日志片段，以及你怀疑的近期代码改动反馈回去。这是提升 gh-fix-ci usage 最快的办法，因为技能可以基于证据细化计划，而不是重新通读整个仓库。