Skip to content
Hidden Logic Lab

Fix a failing GitHub Actions job with an agent CI skill

Claude Code or Cursor uses a SKILL.md that reproduces the failing workflow locally, edits YAML and scripts without disabling checks, and documents what broke and why.

·Coding·35 min·Working

A committed ci-fix skill, a failing run link captured at the start, and a fix PR that re-enables any check the agent temporarily commented out — or explains why that is not allowed.

  1. 1

    Capture the failing run first

    Paste the Actions URL into the session before the agent edits files. Without a pinned run, fixes chase the wrong error.

  2. 2

    Commit the skill beside workflows

    Place under .cursor/skills/ci-fix/SKILL.md and reference it in AGENTS.md for tasks tagged CI or github-actions.

  3. 3

    Reject weaken-the-gate diffs

    If the agent disables a job, require a human ack in the PR. The skill’s hard rules are useless if reviewers accept silent skips.

The prompt to paste

Write SKILL.md for fixing failing GitHub Actions workflows in this repository. The agent must diagnose before editing and must not weaken CI to get green.

Repository context:
[.github/workflows paths, default branch, package manager, how to run the same steps locally e.g. act, npm scripts]
Failing run context (paste when using the skill):
[workflow name, job id, link to run, error excerpt]

SKILL.md must include:
1. Purpose — restore CI truthfully; no silent skip of required jobs.
2. When to use / when not to use (include: stop if failure is flaky infrastructure — note rerun once, then escalate).
3. Hard rules:
   - Never paste secrets, tokens, or ${{ secrets.* }} values into chat or commits.
   - Never remove required jobs, delete fail-fast, or set continue-on-error on merge gates without explicit human approval noted in PR.
   - Prefer fixing the root cause (script, path, cache key, runner image) over pinning arbitrary old versions unless documented.
4. Required inputs: link to failed run, commit sha, and whether the failure started on main or only on a feature branch.
5. Steps:
   - Open the failed job log; quote the first actionable error line (not the whole log).
   - Map the failing step to local command: [list mapping table pattern e.g. "pnpm test" step → pnpm test locally].
   - Reproduce locally; if not reproducible, list environmental diffs (Node version, env vars by name only, cache).
   - Propose minimal diff; run the same local command again after the fix.
   - If workflow YAML changes, validate syntax and note which triggers still apply (pull_request, push, schedule).
   - Update PR description with: root cause, fix, and how you verified (command + exit code).
6. Two example prompts: unit test failure in CI vs cache/path drift in monorepo.
7. Pitfalls: commenting out steps, widening permissions without reason, bumping actions/@v tags without reading changelog, fixing only the symptom error while an earlier step still warns.
8. Done means: checklist — "failure reproduced or documented as env-only", "fix verified locally or re-run link attached", "no secret values in diff", "required checks still required."

Rules:
- Use real workflow file names from repo context; [confirm path] if unknown.
- Do not claim act or other tools work until you note [verify locally].
- Output only SKILL.md.

Flaky CI teaches agents to retry forever. The skill should cap reruns and escalate when the same step fails twice with different errors.

Sample case written by Hidden Logic Lab. Not affiliated with Cursor or Claude Code or GitHub.

More in Coding

Get new cases in your inbox

Weekly notes on new use cases and agent workflows. No product pitches.

Occasional notes on new cases. No product pitches in the first note.