Getting started with coding agents

AI coding agents like Claude Code and Cursor can help you build, debug, and maintain your Buildkite-based workflows more effectively, whether you're configuring Buildkite Pipelines, instrumenting test suites with Buildkite Test Engine, or working with the Buildkite APIs.

This page covers three ways of giving your AI coding agent the context and tools it needs to work with Buildkite products. The same approaches apply across Buildkite Pipelines and Buildkite Test Engine.

Connecting to the MCP server

The Buildkite MCP server uses the Model Context Protocol (MCP) to give your AI agent live access to the Buildkite REST API: build logs, pipeline configuration, cluster state, test suite results, and more.

With the MCP server connected, your agent can:

  • Fetch build logs and identify root causes of failures
  • Query pipeline configuration and suggest improvements
  • Trigger new builds and monitor their progress
  • Access cluster and queue state to debug job routing issues
  • And more

To set up the MCP server, see the MCP server documentation.

Installing Buildkite skills

Buildkite skills capture how an experienced Buildkite user thinks and works, so your AI agent can follow the same approach. They contain documentation, patterns, best practices, and common solutions. Installing these skills into your AI coding agent gives it deep Buildkite expertise without you having to re-explain basic conventions in every session.

The skills available today focus on Buildkite Pipelines, but the MCP server and llms.txt approaches described on this page apply equally to Buildkite Test Engine and Buildkite Package Registries.

Skill Description
Skill Pipelines Description YAML configuration, step types, plugins, caching, parallelism, dynamic pipelines, matrix builds, artifacts, and hooks.
Skill Migration Description Migrate CI/CD workflows from GitHub Actions, Jenkins, CircleCI, Bitbucket Pipelines, or GitLab CI to Buildkite.
Skill Preflight Description Run CI builds against local uncommitted changes using bk preflight before pushing.
Skill Agent Runtime Description buildkite-agent subcommands for annotations, artifacts, metadata, pipeline uploads, OIDC, and locks.
Skill CLI Description bk CLI commands for builds, jobs, pipelines, secrets, artifacts, and authentication.
Skill API Description Buildkite REST API, GraphQL API, webhooks, and authentication patterns.

Skills are organized into two groups:

  • Journey skills: Pipelines and Migration cover end-to-end workflows.
  • Cross-cutting skills: Preflight, Agent Runtime, CLI, and API cover specific capabilities you reach for throughout development.

To install skills, follow the instructions in the Buildkite skills repository.

Using Buildkite documentation as context

Every Buildkite documentation page is available in Markdown format. Append .md to any documentation URL to get the source Markdown file, for example, /docs/pipelines/getting-started.md. Pass these URLs directly to your AI agent as focused context for a specific topic.

For broader context, Buildkite provides llms.txt files per documentation section, listing all pages in that section in a format optimized for LLMs:

Section URL
Section Pipelines URL /docs/pipelines/llms.txt
Section Agent URL /docs/agent/llms.txt
Section Test Engine URL /docs/test-engine/llms.txt
Section Package Registries URL /docs/package-registries/llms.txt
Section APIs URL /docs/apis/llms.txt
Section Platform URL /docs/platform/llms.txt

Use a section's llms.txt as a starting point to give your agent a broad overview of that area, then pass individual .md pages for deeper context on specific tasks.

Next steps

Once you're set up, explore how to run AI agents directly inside your CI pipeline steps in AI agents in Pipelines.