agent-troubleshooting

Diagnose Buildkite job pickup failures using MCP tooling for builds, clusters, and queues.

Updated Jan 19, 2026

Search Tags:#troubleshooting #agent #pipeline #queue #buildkite #diagnose #cluster

Ready to run

npx skills add https://github.com/mcncl/skill-buildkite --skill agent-troubleshooting

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: agent-troubleshooting
Source: https://github.com/mcncl/skill-buildkite/tree/main/skills/agent-troubleshooting
Command: npx skills add https://github.com/mcncl/skill-buildkite --skill agent-troubleshooting

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Helps diagnose why Buildkite jobs are not picked up by agents and identifies bottlenecks in queues and clusters.

Core Features & Use Cases

Retrieve and inspect builds, clusters, and queues to locate where a job is blocked.
Interpret common agent states (scheduled, assigned, accepted) to guide fixes, such as queue or tag mismatches.
Provide actionable remediation steps and diagnostic commands to restore agent throughput.

Quick Start

Ask for the build number or URL and describe the observed agent issue; the system will walk you through diagnosing and resolving the agent bottleneck.

Frequently Asked Questions about agent-troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

Why are my Buildkite jobs not being picked up by agents?▼

Buildkite jobs may remain unassigned due to queue mismatches, missing agent tags, or agent connectivity issues. Diagnosing the build state and cluster configuration helps locate where the job is blocked and identifies the specific bottleneck preventing agent assignment.

How do I diagnose a stuck Buildkite job in my pipeline?▼

To diagnose a stuck Buildkite job, provide the build number or URL. The system queries builds, clusters, and queues to inspect the job state, interprets whether it is scheduled or assigned, and walks you through specific diagnostic commands to resolve the bottleneck.

How does a Buildkite queue mismatch affect agent throughput?▼

A Buildkite queue mismatch prevents jobs from matching available agents, causing scheduled jobs to block indefinitely. Inspecting the queue configuration and comparing it against the agent's target queue identifies the mismatch and restores agent throughput.

Can I use this to troubleshoot agent connectivity issues across multiple Buildkite clusters?▼

Yes, you can troubleshoot agent connectivity issues across Buildkite clusters. The system queries cluster configurations and agent states to determine if agents are failing to accept jobs, providing actionable remediation steps to restore pipeline execution.

What does it mean when a Buildkite job is accepted but not running?▼

When a Buildkite job is accepted but not running, the agent may be experiencing connectivity loss or execution blocks. Interpreting the agent state helps differentiate between queue mismatches and active cluster bottlenecks to determine the correct fix.

What is the best way to fix a Buildkite agent bottleneck?▼

The best way to fix a Buildkite agent bottleneck is to retrieve the build details, inspect the cluster and queue assignments, and apply the provided diagnostic commands. This reveals whether tag mismatches or connectivity failures are stopping job execution.