Preface¶
After submitting a PR, the most torturous part is often not writing the code itself, but waiting for CI to finish – as soon as the red X appears, you have to switch back and forth between the GitHub Actions page and your local terminal: open the failed job, scroll through hundreds of lines of logs, and guess which step crashed. If your team has many workflows and complex matrix builds, troubleshooting a CI failure can easily take up half an afternoon.
If you already use AI programming tools like Cursor, Codex CLI, or Claude Code, the OpenAI official curated skill gh-fix-ci can standardize this workflow: let the Agent pull failed checks and logs with gh, extract key error snippets, propose fixes, and only make code changes after you explicitly approve. This article is organized based on the official SKILL.md and supporting scripts from the openai/skills repository, and all key steps are reproducible.
What is this¶
gh-fix-ci is a skill package that follows the open Agent Skills standard (agentskills.io), maintained by OpenAI and hosted in the .curated directory of the openai/skills repository. Its positioning is clear: when a user asks to debug or fix failed PR checks on GitHub Actions, the Agent should enable this skill to complete the full closed loop of “locate failure → pull logs → summarize causes → develop a solution → get approval → fix code → recheck status” via the GitHub CLI (gh).
It is worth noting that the README of the openai/skills repository marks the repository as deprecated, and points to the OpenAI Plugins repository as the follow-up example source; however, the SKILL.md, scripts, and Codex documentation for gh-fix-ci are still accessible normally, and community installation tools (such as npx skills add) still include this skill, so daily installation and usage are not affected.
Core Features and Highlights¶
1. Focused on GitHub Actions with clear boundaries¶
The skill only handles checks whose detailsUrl points to GitHub Actions runs. If a failed check comes from an external CI provider like Buildkite, the Agent will mark it as external, only report the details link, and will not force deep dives – avoiding wasting tokens and time on systems you cannot control.
2. Built-in inspect_pr_checks.py script¶
The skill directory bundles the Python script scripts/inspect_pr_checks.py, which is specially designed to:
- Call gh pr checks to list all checks on the PR and filter failed items;
- Parse the run ID / job ID from the detailsUrl and pull logs via gh run view --log or job-level logs;
- Compatible with JSON field differences across different versions of gh (such as drift between conclusion and bucket fields);
- Search logs for keywords like error, fail, traceback, assert to extract failure snippets instead of dumping the entire log;
- Support --json output for the Agent to summarize results in a structured way;
- Exit with a non-zero code if failures still exist, which can be used in automated pipelines.
3. Safe workflow of “plan first, act later”¶
The official workflow clearly requires: after summarizing the failure context, first call the create-plan skill (if installed) or draft a repair plan inline, and must obtain explicit user approval before implementing code changes. After making changes, it is recommended to rerun the relevant tests and confirm the status with gh pr checks – this is especially important for high-risk operations like CI fixes.
4. Simple prerequisites¶
The only hard dependency is an installed and authenticated GitHub CLI. The official recommendation is to run gh auth login and confirm that you have repo and workflow permissions via gh auth status – the latter is a necessary scope for pulling Actions logs.
Installation and Activation¶
gh-fix-ci uses the universal SKILL.md format and can be used in multiple AI programming tools. The following methods come from official or Cursor documentation, please choose one according to the tool you are using.
Install in Codex CLI¶
The OpenAI official README provides two methods:
Method 1: Use the built-in skill-installer (in Codex session)
$skill-installer gh-fix-ci
Method 2: Use the community skills CLI
npx skills add https://github.com/openai/skills --skill gh-fix-ci
You need to restart Codex after installation to load the new skill. System skills in the .system directory will be installed automatically, while curated skills require manual installation.
Enable in Cursor¶
Cursor automatically discovers skills from the following directories (official documentation):
| Path | Scope |
|---|---|
.cursor/skills/ |
Project-level |
~/.cursor/skills/ |
User-level (global) |
You can put the entire gh-fix-ci directory (including SKILL.md and scripts/) into one of the above paths, for example:
git clone --depth 1 https://github.com/openai/skills.git /tmp/openai-skills
cp -r /tmp/openai-skills/skills/.curated/gh-fix-ci ~/.cursor/skills/
The directory structure should look similar to:
.cursor/skills/gh-fix-ci/
├── SKILL.md
├── scripts/
│ └── inspect_pr_checks.py
├── agents/
│ └── openai.yaml
└── assets/
Restart Cursor or manually trigger it by entering /gh-fix-ci in the Agent conversation. The Agent will also automatically match this skill when you mention contexts like “CI is red” or “PR checks failed”.
In other tools like Claude Code¶
Tools that follow the Agent Skills standard usually support .claude/skills/ or .agents/skills/ directories, and the installation method is similar to Cursor – just copy the skill folder to the corresponding directory. Cursor’s documentation also notes that it will support paths like .claude/skills/ and .codex/skills/.
Typical Usage Examples¶
Prerequisite: Confirm gh is authenticated¶
gh auth login
gh auth status
If auth status shows that the workflow scope is missing, you need to log in again and select the corresponding permissions.
Quickly troubleshoot the current branch PR¶
In the repository root directory, you can directly run the skill’s built-in script (replace the path with your skill installation location):
python ~/.cursor/skills/gh-fix-ci/scripts/inspect_pr_checks.py --repo "."
When --pr is not specified, the script will automatically parse the PR associated with the current branch via gh pr view --json number. The output example includes: failed check name, Run ID, workflow information, and the extracted Failure snippet.
Specify the PR number or URL:
python ~/.cursor/skills/gh-fix-ci/scripts/inspect_pr_checks.py \
--repo "." \
--pr "123"
Add --json for machine-readable output:
python ~/.cursor/skills/gh-fix-ci/scripts/inspect_pr_checks.py \
--repo "." \
--pr "123" \
--json
Adjust the log window size:
python ~/.cursor/skills/gh-fix-ci/scripts/inspect_pr_checks.py \
--repo "." \
--max-lines 200 \
--context 40
Manual fallback (equivalent operations when the script is unavailable)¶
The official SKILL.md also records a pure gh command chain, which is convenient for manual or step-by-step Agent execution:
# 1. View the PR check list
gh pr checks 123 --json name,state,bucket,link,startedAt,completedAt,workflow
# 2. Extract run_id from detailsUrl and view the run details
gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha
# 3. Pull the full log
gh run view <run_id> --log
# 4. If the log is still being generated, pull job-level logs instead
gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs"
Prompt words in Agent conversations¶
Codex has configured a default prompt for this skill (see agents/openai.yaml):
Inspect failing GitHub Actions checks in this repo, summarize root cause, and propose a focused fix plan.
You can also describe the scenario directly in Chinese, for example:
The CI for this PR failed, help me use gh to check which check failed and what specific errors are in the logs. First give the repair plan, and I will make changes after confirmation.
After the Agent enables gh-fix-ci, it will execute step by step according to the workflow: authentication check → parse PR → run script or fallback → summarize snippets → draft plan → wait for your approval.
Applicable Scenarios and Notes¶
Who it is suitable for:
- Developers who regularly submit PRs on GitHub and rely on Actions for lint/test/build;
- Repository maintainers who maintain multiple workflows and often have “only one combination failing” in matrix builds;
- Teams that want to hand off “CI failure troubleshooting” to AI Agents but retain manual approval rights.
Typical scenarios:
- A job suddenly fails before PR merge, and you need to quickly locate whether the problem is a test assertion, dependency installation, or environment configuration;
- Flaky tests that cannot be reproduced locally and can only be debugged via Actions logs;
- New colleagues who are not familiar with gh commands, hoping that the Agent will pull logs and explain the errors for them.
Notes:
1. Only covers GitHub Actions. External checks such as Jenkins, CircleCI, Buildkite will only return the URL and will not be automatically fixed.
2. You must run gh auth login first, and you need the workflow scope; otherwise the script will exit with an error directly during the ensure_gh_available phase.
3. Repairs require explicit approval. The skill design deliberately prevents Agents from modifying workflows or test code without confirmation – CI configuration changes have a wide impact, so this step cannot be skipped.
4. Logs may return log_pending status while still being generated. You need to wait for the job to finish before checking, or use the job-level API instead.
5. If you have installed the create-plan skill, gh-fix-ci will prioritize calling it to generate a structured repair plan, and the two can be used together.
Summary¶
CI failure troubleshooting is one of the most frequent pain points for developers. gh-fix-ci encapsulates OpenAI’s official curated experience into a reusable Agent Skill: use gh to automatically pull PR checks and Actions logs, use the bundled script to extract failure snippets, and then follow the secure workflow of “plan → approve → fix → recheck”. Whether you are a Codex, Cursor, or Claude Code user, just put the skill directory into the corresponding path and make sure gh is authenticated, and the next time the PR red X lights up, just let the Agent help you check it out.
Official address: https://github.com/openai/skills/tree/main/skills/.curated/gh-fix-ci
Codex Skills documentation: https://developers.openai.com/codex/skills