Terminal
Terminal/Skill
Investigates failing CircleCI builds through the CircleCI MCP server, finding failed tests, flaky tests, and root causes.
By CircleCI
Works with
npx skills add circleci-public/skills --skill debug-ci-failuresYou are helping the user debug CircleCI build failures. Follow this workflow to systematically diagnose and resolve CI issues.
The CircleCI MCP server must be configured with the name circleci-mcp-server. If it's not available, let the user know they need to add the CircleCI MCP server to their configuration before using this skill.
The CircleCI MCP tools are deferred and must be loaded before use. Use ToolSearch with the query +circleci to discover and load the available CircleCI tools. Verify that the tools listed in this skill's allowed-tools are available before proceeding.
Determine which CircleCI project to investigate. Use one of these approaches in order of preference:
git remote get-url origin and the branch with git branch --show-current.mcp__circleci-mcp-server__list_followed_projects to show the user their projects and let them pick one.Use mcp__circleci-mcp-server__get_latest_pipeline_status to quickly triage the current state of the pipeline:
This avoids unnecessary log fetching when there is nothing to debug.
Use mcp__circleci-mcp-server__get_build_failure_logs to retrieve the failure logs. Pass the appropriate parameters based on how the project was identified:
workspaceRoot, gitRemoteURL, and branchurl parameterprojectSlug and branchUse mcp__circleci-mcp-server__find_flaky_tests to check if any tests in the project are known to be flaky. This helps distinguish between genuine failures and intermittent issues.
If flaky tests are found, clearly flag which failures in the logs might be caused by flaky tests.
If the failure involves test failures, use mcp__circleci-mcp-server__get_job_test_results to get detailed test metadata including:
Always use filterByTestsResult: 'failure' when investigating failures so the tool returns only failed tests instead of the full test suite.
Analyze the tool output directly in your response. Do not write scripts or create temporary files to process the results.
If the output includes an <MCPTruncationWarning>, the data was too large to
return in full. Work through these fallbacks in order:
.../jobs/123) instead of a pipeline or branch-level URL.filterByTestsResult: 'failure' with get_job_test_results to return only failed tests.Based on the collected information, provide:
After diagnosis, offer to:
mcp__circleci-mcp-server__rerun_workflow with the workflowId from the Step 2 pipeline status output. Set fromFailed: true to rerun only from the failed job instead of rerunning the entire workflow.