mcpField
C
circleci-builds

circleci-builds

github.com/circleci-publicCloud & DevOps763 installsUpdated 1w ago
Repository

About circleci-builds

A skill for diagnosing and fixing failing CircleCI pipelines, intended for developers handling build incidents. It focuses on tracing the first failure signal, making a minimal evidence-based change, and stating validation criteria and residual risks.

Key features

  1. 01Identify the first failing step
  2. 02Classify config, environment, and test failures
  3. 03Make minimal root-cause-based fixes
  4. 04Define validation and report risks
  5. 05Distinguish deterministic from transient failures

Use cases

  1. 01Investigate a failing CircleCI pipeline
  2. 02Decide whether a failure merits a retry
  3. 03Fix a build or test regression
  4. 04Report the cause and validation plan

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/circleci-public/skills --skill circleci-builds

After installing, type/circleci-buildsin Claude Code to confirm it loaded.

Bundled filesreferences/transient-vs-deterministic.md

Details

From the project README

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.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.

Comments

Markdown supported