---
name: buildkite-mcp-debugging
description: >-
  Debug live Buildkite builds and stay accurate using the Buildkite MCP server
  and real-time documentation search. Use when investigating why a build/step
  failed, fetching build logs or annotations, listing pipelines/builds/agents,
  or when you need to verify current Buildkite syntax/behavior against the live
  docs. Triggers on "why did my build fail", "Buildkite logs", "debug the
  pipeline", or "check the latest Buildkite docs".
allowed-tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
---

# Buildkite live debugging & real-time accuracy

This skill does two things: **inspect real builds** via the Buildkite MCP
server, and **keep answers accurate** by checking the live documentation.

> References (verify here):
> - MCP overview: https://buildkite.com/docs/apis/mcp-server
> - Configure AI tools: https://buildkite.com/docs/apis/mcp-server/remote/configuring-ai-tools
> - Toolsets: https://buildkite.com/docs/apis/mcp-server/tools/toolsets

## A. Debugging with the Buildkite MCP server

The MCP server exposes Buildkite read/write operations as tools. It is **not
bundled** in this plugin (so you never ship credentials); the user adds it once.

### One-time setup (user runs this)
```bash
# Full access:
claude mcp add --transport http buildkite https://mcp.buildkite.com/mcp

# Read-only (recommended for debugging — can't mutate anything):
claude mcp add --transport http buildkite-ro https://mcp.buildkite.com/mcp/readonly \
  --header "X-Buildkite-Toolsets: user,pipelines,builds,agents"
```
The remote server authenticates via Buildkite's OAuth flow on first use. See the
README "Connecting the Buildkite MCP server" section.

### Using it
Once connected, MCP tools appear (typically prefixed `mcp__buildkite__*`). If
you don't see them, use ToolSearch to load them. Toolsets group the tools:
- `user` — who am I / which org (validate the token first).
- `pipelines` — list/get pipelines (and create/update with write access).
- `builds` — list/get builds, get a build's jobs, fetch logs, wait for builds.
- `agents` — which agents are connected and their state.

### Debugging workflow
1. **Confirm access**: call the `user`/token tool to verify org + scope.
2. **Locate the build**: list builds for the pipeline (filter by branch/state),
   or get a specific build by number.
3. **Find the failing job/step**: get the build's jobs; identify the non-zero /
   failed one and which hook or command it was.
4. **Read the log**: fetch that job's log. Look for: the failing command, the
   last hook that ran, `set -e` aborts, missing env vars, and any
   `+++`/`^^^` Buildkite log group markers near the failure.
5. **Correlate to code**: map the failure to the pipeline step or plugin hook.
   For plugin issues, hand off to `buildkite-plugin-dev`; for pipeline structure,
   to `pipeline-architecture` (and validate fixes with `--dry-run`).
6. **Propose a fix** and, if the user wants, re-run via the MCP write tools.

Prefer the **read-only** endpoint when you're only investigating.

## B. Real-time documentation accuracy

Buildkite evolves (hook behavior, plugin tags, CLI flags, MCP toolsets). Do not
rely on memory for version-sensitive details — verify:

1. **Search** with WebSearch scoped to the docs:
   `WebSearch("Buildkite <topic>", allowed_domains=["buildkite.com"])`.
2. **Open** the authoritative page with WebFetch to read specifics (note: some
   environments restrict outbound fetches; WebSearch summaries still help).
3. **Prefer** `buildkite.com/docs/...` over blog posts or third-party sources.
4. When you state a version-specific fact (e.g. "OIDC tokens are redacted from
   agent 3.104.0"), cite the doc you confirmed it from.

Key doc entry points:
- Plugins: https://buildkite.com/docs/pipelines/integrations/plugins
- Pipeline config: https://buildkite.com/docs/pipelines/configure
- Agent hooks: https://buildkite.com/docs/agent/hooks
- CLI reference: https://buildkite.com/docs/agent/cli/reference
- Security/OIDC: https://buildkite.com/docs/pipelines/security

## Related
- `pipeline-architecture` (validation/`--dry-run`), `buildkite-plugin-dev`,
  `pipeline-security`.