gh-fix-ci

Overview of gh-fix-ci skill

gh-fix-ci is a focused GitHub Actions troubleshooting skill for failing PR checks in a repository where gh access is available. It helps you inspect the failing check, pull the most relevant log snippet, summarize what broke, and prepare a fix plan before any code change is made.

This skill is best for maintainers and agents doing gh-fix-ci for CI Troubleshooting on GitHub-hosted workflows, especially when the failure is noisy and you need a fast path from red check to actionable diagnosis. It is less useful for external CI providers like Buildkite, because the skill explicitly treats those as out of scope and only surfaces the details URL.

What the skill does well

The gh-fix-ci skill is strongest when the problem is in GitHub Actions logs and you need a structured triage flow, not a generic “fix my build” prompt. It expects authenticated gh access, resolves the PR, inspects checks, and narrows the failure to the part worth reading first.

Where it fits

Use gh-fix-ci when the main task is to identify why a PR check failed, not to redesign the repo’s CI system. It is a good fit if you want a repeatable workflow that starts with evidence, then moves to a concise fix plan, then implementation only after approval.

Main constraint to know

The skill depends on GitHub CLI access and repo/workflow scopes. If gh auth status is not already valid, the workflow stops early so you can authenticate before any analysis begins.

How to Use gh-fix-ci skill

Install and verify access

For gh-fix-ci install, add the skill to your skills set with:

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

Before using it, confirm gh works in the target repo:

gh auth status

If needed, run gh auth login with the right repo and workflow scopes, then retry. Without that access, the skill cannot inspect checks or fetch logs.

Start with the right input

The best gh-fix-ci usage starts with a repo path and either a PR number, PR URL, or the current branch PR. A strong prompt looks like:

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

That is better than “CI is broken” because it gives the skill a concrete target, a scope boundary, and an approval gate.

Read these files first

For a quick gh-fix-ci guide, inspect SKILL.md first, then scripts/inspect_pr_checks.py, agents/openai.yaml, and LICENSE.txt. Those files show the intended workflow, the supported quick-start path, the default prompt, and the repository’s operational shape.

If you want to understand execution details, scripts/inspect_pr_checks.py is especially useful because it reveals how failing checks are collected, how log snippets are filtered, and what the script considers a relevant failure.

Use the workflow in practice

A practical sequence is: authenticate, resolve the PR, inspect checks, pull the failing log context, summarize the root cause, then ask for approval before implementing a fix. If a plan-oriented skill like create-plan exists in your environment, use it; otherwise, request a concise inline plan.

For best results, provide:

• repo path
• PR number or URL
• whether you want diagnosis only or diagnosis plus fix
• any known noisy jobs, flaky checks, or external providers to ignore

gh-fix-ci skill FAQ

Is gh-fix-ci only for GitHub Actions?

Yes, primarily. It is designed to debug failing checks that run in GitHub Actions via gh. If the failure comes from an external provider, the skill will not deeply analyze that system and should only point you to the details URL.

Do I need the gh-fix-ci skill if I can write a prompt myself?

You can write a one-off prompt, but the gh-fix-ci skill adds a repeatable workflow: authenticate, resolve the PR, inspect checks, summarize the failure snippet, and pause before changes. That structure reduces guesswork and makes the output more reliable than a vague debugging prompt.

Is gh-fix-ci beginner-friendly?

Yes, if the user can identify the repo and PR. The skill handles the CI triage sequence, but beginners still need valid gh authentication and a willingness to provide a specific PR target.

When should I not use gh-fix-ci?

Do not use it when the problem is clearly outside GitHub Actions, when you do not have gh access, or when you only need a broad CI architecture review. It is optimized for failing PR checks, not for general DevOps advice.

How to Improve gh-fix-ci skill

Give the skill a sharper target

The biggest quality gain comes from naming the repo, PR, and symptom precisely. “PR 92 fails in test after dependency updates” is much better than “fix CI,” because it helps gh-fix-ci focus on the right job and filter the right log segment.

Tell it what kind of output you want

If you want the skill to stop at analysis, say so. If you want a fix plan first and code changes only after approval, say that too. The skill is built around diagnosis plus plan, so explicit instructions reduce accidental overreach.

Include the CI context that changes debugging

Mention the runner, workflow name, flaky history, or any external system involved. This matters because gh-fix-ci is strongest when it can separate actionable GitHub Actions failures from unrelated noise and out-of-scope providers.

Iterate from log evidence, not guesses

If the first pass produces a partial diagnosis, feed back the exact failing job name, the log snippet, and any recent code change you suspect. That is the fastest way to improve gh-fix-ci usage, because the skill can refine the plan from evidence instead of re-reading the entire repository.