circleci-builds — Codex skill: CircleCI failures and setup
This skill investigates failed CircleCI jobs, traces likely root causes, and guides small fixes. Use it when a build, test, or pipeline step breaks.
npx skills add openai/plugins --skill builds -a codexWhat circleci-builds does
The skill starts with the first failing job and step instead of treating every downstream error as separate. It classifies the signal as a configuration problem, toolchain mismatch, dependency or cache issue, test or build regression, or an external transient failure.
It then narrows the patch to files tied to the confirmed cause. The result includes local checks where possible, the expected success signal for a CircleCI rerun, and remaining risk. The reference references/transient-vs-deterministic.md supports retry decisions; ../config/references/test-results-and-splitting.md covers missing test metadata, flaky reruns, test splitting, and JUnit XML setup.
Do not mix an incident fix with unrelated refactoring. The investigation uses the pipeline, workflow, or job identifier, branch, commit SHA, first failing step, key log lines, and whether the same commit fails again.
What it helps with
- locate the first failing CircleCI step
- classify a broken job by root-cause type
- patch build or test configuration
- check whether the same commit reproduces the failure
- record validation signals and residual risk
Example prompts for the agent
- Investigate this failed CircleCI job and identify the first meaningful error in the logs.
- Trace the failing workflow for this branch and commit SHA, then propose the smallest safe patch.
- Decide whether to rerun this job or change the configuration, test setup, or build code.
How to install circleci-builds
1Skills CLI (Vercel)
npx skills add openai/plugins --skill builds -a codex2Manually: put the files in place
.agents/skills/builds/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add openai/plugins --skill builds -a claude-code2Manually: put the files in place
~/.claude/skills/builds/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/builds/
Manually: put the files in place
.cursor/skills/builds/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install openai/plugins builds2Manually: put the files in place
.github/skills/builds/SKILL.mdPlatform CLI
gemini skills install https://github.com/openai/plugins --path plugins/circleci/skills/buildsManually: put the files in place
.devin/skills/builds/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: Codex skills: how to install, where they live, how to call them
Questions about circleci-builds
How do I install circleci-builds in Codex?
Run npx skills add openai/plugins --skill builds -a codex, then use .agents/skills/builds/SKILL.md.
What does circleci-builds do?
It examines failed CircleCI pipelines, workflows, and jobs, forms a root-cause hypothesis from the first failure, and guides a minimal fix with validation criteria.
What information does the skill need to investigate a CircleCI failure?
Provide the pipeline, workflow, or job identifier, branch, commit SHA, first failing step, important log lines, and whether a rerun on the same commit reproduces the problem.
Source text
SKILL.md · MIT
--- name: circleci-builds description: Diagnose and fix failing CircleCI builds quickly and safely. Use when users ask to investigate failed CircleCI jobs, triage flaky pipelines, identify root causes from logs, and implement minimal fixes in configuration, test setup, or build-related code paths. --- # CircleCI Builds ## Overview Use this skill to turn failing CircleCI pipelines into actionable fixes with clear evidence. Prioritize fast root-cause isolation, minimal safe patches, and explicit validation criteria. Read `references/transient-vs-deterministic.md` when deciding whether a failure should be fixed in code/config, retried, mitigated with rerun behavior, or reported as external/transient. Read `../config/references/test-results-and-splitting.md` when the failure involves missing test metadata, flaky test reruns, test splitting, or JUnit XML setup. ## Inputs To Gather - Failing pipeline/workflow/job identifier - Branch and commit SHA - First failing step and key log lines - Whether rerun on same commit reproduces failure ## Workflow 1. Identify the primary failing signal. - Record the first failing job and step, not every downstream failure. 2. Classify issue type. - Config syntax/reference issue - Environment/toolchain mismatch - Dependency/cache issue - Test or build regression - External/transient failure 3. Apply the smallest viable fix. - Patch only files tied to confirmed root cause. - Keep workaround scope narrow. 4. Validate. - Run highest-signal local checks when possible. - Define expected CircleCI success signals for the rerun. 5. Report residual risk. - Call out unverified assumptions and likely follow-up checks. ## Guardrails - Do not hide deterministic failures with blanket retries. - Avoid mixing unrelated refactors into incident fixes. - Treat external service outages as report-and-mitigate unless user asks for deeper redesign. - Keep confidence levels explicit when logs are incomplete. - Do not recommend automatic reruns or flaky-test workflows until the failure is classified as plausibly transient. ## Output Contract Provide: 1. Failure summary (pipeline/workflow/job/step). 2. Root-cause hypothesis with confidence. 3. Applied changes with file list. 4. Validation plan and expected pass signal. 5. Remaining risk.
© CircleCI · MIT · openai/plugins
