developing-buildkite-pipelines

# Developing Buildkite Pipelines

## Overview

**Reference official Buildkite documentation before making pipeline changes.** Your training data may contain outdated syntax, deprecated patterns, or missing features.

## When to Use

Use this skill when:
- Writing or modifying pipeline.yml files
- Creating dynamic pipelines
- Debugging pipeline configuration errors
- Adding new step types (command, trigger, block, wait)
- Configuring dependencies, artifacts, or parallelism
- Setting up Buildkite plugins
- Configuring or debugging Buildkite plugins

Do NOT use for:
- Checking build status (use buildkite-status skill)
- General CI/CD concepts (language-agnostic advice)

## The Iron Rule

**NEVER propose Buildkite YAML without consulting the reference docs.**

## Detecting buildkite-builder

**Check for buildkite-builder usage before proceeding:**

buildkite-builder is detected when BOTH conditions are true:
1. `.buildkite/pipeline.yml` references Docker image containing "buildkite-builder"
2. Pipeline Ruby files exist: `.buildkite/pipeline.rb` OR `.buildkite/pipelines/*/pipeline.rb`

When detected, announce:

> "I see you're using buildkite-builder for dynamic pipeline generation. I'll work with your pipeline.rb files and reference the Ruby DSL."

Then load buildkite-builder reference documentation as needed.

## Working with Plugins

### Before Modifying Plugin Configuration

When editing pipeline steps that use plugins:

1. **Identify plugins** - Note all `plugins:` entries in the step
2. **Determine source:**
   - Default org `buildkite-plugins` if no org specified
   - Parse explicit org from `{org}/{plugin}#version` format
3. **Load documentation:**
   - **Cached:** Check `@references/plugins/{plugin-name}.md`
   - **Official (not cached):** Fetch from Buildkite directory or GitHub
   - **Internal:** Fetch README from `github.com/{org}/{plugin}-buildkite-plugin`
4. **Match versions** - If pipeline specifies version, fetch that version's docs from GitHub tag

### F