agentleFS
Sign inStart free
KhaledSaeed18KhaledSaeed18/dotclaude/skills/engineering/fix-ci/SKILL.md

fix-ci

Skill5 starsChanged 4 months agoMITView on GitHub

Diagnose and fix a failing CI run by pulling the actual failure logs (gh run view --log-failed), reproducing the failure locally, fixing the root cause rather than the symptom, and verifying green before and after pushing. Use when a GitHub Actions run is red, a PR check is failing, or CI passes locally but fails remotely.

We split this skill into the rules it gives an agent

3 rules. 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 33 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the run belongs to a PR, also check which check is required and whether the failure is new to this branch:

    line 19
  2. Distinctive:

    Run the failing step's actual command from the workflow file, not your usual local equivalent:

    line 28
  3. Distinctive:

    Locally: run the exact failing command again and confirm it passes, plus the project's full check suite so the fix didn't break a sibling.

    line 52

“Common” is measured: kept by at least 6 in 10 of the 33 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Fix the failure CI actually reported, not the one you assume it hit. The log line that failed the job is evidence; everything else is guessing. Pull it first, reproduce it locally second, and only then change code.

Step 1: Get the real failure

# What failed, and on which commit
gh run list --limit 10
gh run view <run-id> --log-failed 2>&1 | tail -80

Read the failed step's output completely. Identify: the failing step name, the exact error, and whether the failure is in your change or in the pipeline itself (setup step, cache, runner image, flaky network). If several jobs failed, find the first failure in dependency order; downstream jobs often fail as a consequence.

If the run belongs to a PR, also check which check is required and whether the failure is new to this branch:

gh pr checks <pr-number>
git log --oneline origin/main..HEAD

Step 2: Reproduce locally

Run the failing step's actual command from the workflow file, not your usual local equivalent:

# Read the workflow to get the exact command and environment
cat .github/workflows/<workflow>.yml
  • Reproduces locally: it is a code problem. Debug it normally (the systematic-debugging skill applies) and fix the root cause.
  • Passes locally, fails in CI: the difference is environmental. Compare in this order: dependency install mode (--frozen-lockfile vs a loose local install), Node/tool versions (CI pins one; check yours), OS differences (case-sensitive paths, line endings), missing env vars or secrets, and cache staleness. State which difference explains the failure before changing anything.
  • Not reproducible and clearly infrastructure (runner network blip, rate limit, timeout on a step that touches nothing you changed): rerun once with gh run rerun <run-id> --failed. If it fails the same way twice, it is not flake; go back to evidence.

Step 3: Fix the cause, not the check

Make the smallest change that addresses the named root cause. Things that are not fixes:

  • Deleting or skipping the failing test to make CI green.
  • Loosening an assertion until it passes.
  • Adding continue-on-error or removing the step.
  • Bumping a timeout without knowing why the step got slower.

Any of these may be proposed to the user with justification, but never applied silently as "the fix".

Step 4: Verify green, twice

  1. Locally: run the exact failing command again and confirm it passes, plus the project's full check suite so the fix didn't break a sibling.
  2. Remotely: push, then watch the run to completion rather than assuming:
gh run watch <new-run-id> --exit-status

Report the root cause, the fix, and the green run link. If the failure was flake, say so explicitly and note the rerun that confirmed it.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free