CI Doctor

An Agent Skill that teaches your AI to fix failing CI/CD pipelines.

Paste a red build log and your AI tells you the root cause, the durable fix (not a --legacy-peer-deps paper-over), and whether the failure was a real bug or a transient blip that should have just retried itself.

It is built from Latchkey Learn, a knowledge base of thousands of real CI/CD failures across GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure Pipelines, and Bitbucket, covering npm/yarn/pnpm, pip/poetry, Docker, Maven/Gradle, Go, Cargo, Kubernetes, Terraform, git, and the major test runners.

Why

Hand a generic assistant a failing CI log and it reaches for whatever turns the line green: npm ci --legacy-peer-deps, pip install --no-deps, || true, deleting the failing test. The symptom clears, the cause stays, the build breaks again next week.

CI Doctor makes two judgments a generic assistant usually skips:

1. Durable fix over the cheap unblock. Fix the cause, not the symptom.
2. Transient/mechanical vs real. A registry timeout, a Docker Hub rate limit, an out-of-memory step, a disk that filled mid-build: these aren't bugs in your code. They're failures that should retry themselves. CI Doctor names the failure class so you know whether to debug your code or just stop paying for flaky reruns.

Example

You paste:

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error peer react@"^19.0.0" from @acme/charts@5.1.0

CI Doctor answers:

• Root cause: @acme/charts@5.1.0 needs React 19, but your project pins React 18.
• Durable fix: align the versions (downgrade @acme/charts to its React 18 line, or upgrade React), then regenerate and commit the lockfile. Not --legacy-peer-deps, which only hides the mismatch until it breaks at runtime.
• Failure class: a real dependency conflict, not transient. Retrying will not help.
• Source: links the canonical write-up on Latchkey Learn.

Install

CI Doctor is a standard Agent Skill: a SKILL.md plus a references/ folder. Any agent that can read local files and run grep can use it.

Claude Code

# Personal (available in every project):
git clone https://github.com/latchkey-dev/CI-Doctor.git ~/.claude/skills/ci-doctor

# or per-project (committed with your repo):
git clone https://github.com/latchkey-dev/CI-Doctor.git .claude/skills/ci-doctor

Claude Code auto-discovers it. Next time a build fails, just paste the log.

Claude.ai / Claude Desktop

Upload it as a Skill in your Claude settings (claude.ai/customize/skills). This requires a paid plan with code execution enabled; see Anthropic's Agent Skills docs for the current steps. Package the folder first:

git clone https://github.com/latchkey-dev/CI-Doctor.git ci-doctor
zip -r ci-doctor.zip ci-doctor -x '*/.git/*'

That produces ci-doctor.zip with ci-doctor/SKILL.md at the archive root, which is the shape the uploader expects.

Cursor, Windsurf, and other agents

Clone the repo into your project, then point your agent's rules/context at SKILL.md (for example @SKILL.md in Cursor, or a .cursor/rules entry). The references/ catalog is plain text, so any agent that can grep a file and fetch a URL gets the full benefit.

How it works

• references/index.tsv is a catalog of 4,555 known failures (signature, fix, URL). The AI greps it for your error, never loading the whole thing.
• references/self-healing-playbooks.md and references/self-healable-errors/*.md inline the transient/mechanical failures in full (90 self-heal playbooks plus 672 healable errors), so those work with no network access. They are grouped by class: network, setup, memory, timeout, disk.
• The remaining errors are fetched on demand from latchkey.dev/learn, so the full catalog needs network while the bundled core does not.

Regenerating the knowledge base

Maintainer-only: references/ is generated from the Latchkey Learn content source (which is not distributed), so most users never need this.

node scripts/generate-skill.mjs --content <path-to-learn-content>

Pure Node, no dependencies. Run it after the Learn content updates rather than editing the generated files by hand.

About Latchkey

Latchkey runs your GitHub Actions on managed runners that automatically detect, fix, and retry transient failures (the exact network, setup, memory, timeout, and disk failures this skill helps you recognize) so flaky builds turn green without a human in the loop. This skill is free and standalone; you do not need a Latchkey account to use it.

License

The skill code (SKILL.md, scripts/, this README) is MIT, see LICENSE. The bundled knowledge base under references/ is generated from Latchkey Learn and provided free for use with this skill.