Skip to content
Skills Library
DevOps & cloud · Building & coding

developing-pipelines

/developing-pipelines

Use when creating, modifying, or debugging Buildkite pipeline YAML files - ensures current syntax from official docs, validates configurations before proposing changes, and references Buildkite best practices instead of relying on training data

Licence
MIT
Last repository change
19.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
48
Scripts
1
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: update-docs.sh

What it does and when to use it

Use when creating, modifying, or debugging Buildkite pipeline YAML files - ensures current syntax from official docs, validates configurations before proposing changes, and references Buildkite best practices instead of relying on training data

Original author description

Use when creating, modifying, or debugging Buildkite pipeline YAML files - ensures current syntax from official docs, validates configurations before proposing changes, and references Buildkite best practices instead of relying on training data

How it works

  1. Overview
  2. When to Use
  3. The Iron Rule
  4. Detecting buildkite-builder
  5. Working with Plugins
  6. Workflow
  7. buildkite-builder Troubleshooting Mode
  8. Common Mistakes
  9. Dynamic Pipelines Pattern
  10. Debugging Configuration Errors
Original SKILL.md headings · 260 lines, 1,065 words
SKILL.md preview
---
name: developing-pipelines
description: Use when creating, modifying, or debugging Buildkite pipeline YAML files - ensures current syntax from official docs, validates configurations before proposing changes, and references Buildkite best practices instead of relying on training data
---

# 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](references/plugins/)
   - **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

### Fetching Plugin Documentation

**Buildkite directory (latest):**
```
https://buildkite.com/resources/plugins/{org}/{plugin-name}-buildkite-plugin
```

**GitHub README (version-specific):**
```
https://github.com/{org}/{plugin-name}-buildkite-plugin/tree/{version}
```

### Plugin Discovery

**"Is there a plugin for X?"**

1. Check [references/plugins/index.md](references/plugins/index.md) for common plugins by category
2. Fetch Buildkite directory: `https://buildkite.com/resources/plugins/`
3. Search by task type (caching, docker, secrets, etc.)

**Internal plugins:**

Search org's GitHub for repos matching `*-buildkite-plugin`

## Workflow

### 1. Detect buildkite-builder (if present)

Check for buildkite-builder usage:
- Docker image in `.buildkite/pipeline.yml` contains "buildkite-builder"
- `.buildkite/pipeline.rb` OR `.buildkite/pipelines/*/pipeline.rb` exists

If detected, announce and load buildkite-builder context.

### 2. Read Official Docs FIRST

**For YAML pipelines:**

Before writing or modifying pipeline YAML:

```markdown
**I need to reference the Buildkite documentation for [specific feature].**

Let me read [references/[relevant-doc].md](references/).
```

**For buildkite-builder pipelines:**

Before writing or modifying pipeline.rb:

```markdown
**I need to reference buildkite-builder documentation for [specific feature].**

Let me read [references/buildkite-builder/[relevant-doc].md](references/buildkite-builder/).
```

**Available references:**
- `step-types.md` - Command, trigger, block, wait, input steps
- `dynamic-pipelines.md` - Generating steps programmatically
- `dependencies.md` - Using depends_on, parallel steps
- `environment-variables.md` - Setting and using env vars
- `conditionals.md` - if/branches for conditional execution
- `artifacts.md` - Uploading and downloading build artifacts

See [references/index.md](references/index.md) for complete list.

**Plugin references (see [references/plugins/index.md](references/plugins/index.md) for full list):**
- `plugins/docker.md` - Docker container execution
- `plugins/docker-compose.md` - Multi-container environments
- `plugins/artifacts.md` - Artifact upload/download
- `plugins/ecr.md` - AWS ECR authentication
- `plugins/cache.md` - Dependency caching

**buildkite-builder references (when detected):**
- `buildkite-builder/index.md` - Overview and when to use
- `buildkite-builder/dsl-syntax.md` - Core DSL step types
- `buildkite-builder/step-attributes.md` - Common attributes
- `buildkite-builder/templates.md` - Reusable step templates
- `buildkite-builder/extensions.md` - Custom DSL and extensions
- `buildkite-builder/conditionals.md` - Conditional step generation
- `buildkite-builder/dependencies.md` - Step dependencies
- `buildkite-builder/artifacts.md` - Artifact handling
- `buildkite-builder/plugins.md` - Plugin usage in DSL
- `buildkite-builder/environment.md` - Environment variables

See [references/buildkite-builder/index.md](references/buildkite-builder/index.md) for complete guide.

### 3. Validate Syntax

After proposing changes, ALWAYS mention validation:

```bash
# Validate locally before pushing
buildkite-agent pipeline upload --dry-run < pipeline.yml

# Or validate a generated pipeline
./generate-pipeline.sh | buildkite-agent pipeline upload --dry-run
```

**For buildkite-builder pipelines:**

After proposing pipeline.rb changes:

1. Scan for ENV variable usage
2. Generate Docker validation command with placeholders
3. List detected environment variables

```bash
# Generate YAML locally
docker run --rm \
  -v $(pwd)/.buildkite:/workspace/.buildkite \
  -e BUILDKITE_BRANCH=main \
  -e BUILDKITE_COMMIT=abc123def \
  -e BUILDKITE_BUILD_NUMBER=1 \
  gusto/buildkite-builder:4.13.0

# Validate generated YAML
docker run ... | buildkite-agent pipeline upload --dry-run
```

Note: List any custom ENV variables found in pipeline.rb and suggest setting real values if needed.

### 4. Load Plugin Documentation

Before modifying any step with plugins:

1. **Identify all plugins** in the step's `plugins:` block
2. **For each plugin:**
   - Check [references/plugins/{name}.md](references/plugins/) for cached docs
   - If not cached, fetch from Buildkite directory or GitHub
   - If version specified, fetch version-specific docs
3. **Then proceed** with changes using accurate configuration reference

See [references/plugins/index.md](references/plugins/index.md) for lookup workflow and common plugins.

## buildkite-builder Troubleshooting Mode

When user mentions errors, "not generating", "YAML looks wrong", or validation failures with buildkite-builder:

1. **Read pipeline.rb** - Understand the Ruby DSL
2. **Run Docker command** - Generate YAML to see actual output
3. **Compare output** - Expected vs actual YAML
4. **Reference both docs** - buildkite-builder DSL AND Buildkite YAML docs
5. **Identify issue** - Where Ruby DSL produces unexpected YAML
6. **Propose fix** - Modify pipeline.rb to fix generation

This mode switches from Ruby-first to YAML-aware debugging.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Writing YAML from memory | Read step-types.md first |
| "This should work..." | Validate with --dry-run |
| Custom script without checking plugins | Search buildkite.com/plugins |
| Speculating about errors | Check references/troubleshooting.md |
| Assuming syntax from training data | Verify against current docs |

## Dynamic Pipelines Pattern

When generating steps programmatically:

1. **Reference dynamic-pipelines.md** for current patterns
2. **Use Buildkite SDK** if available (see dynamic-pipelines.md)
3. **Validate generated output** with --dry-run
4. **Consider official examples** before custom implementations

```bash
# Standard pattern from official docs
.buildkite/pipeline.sh | buildkite-agent pipeline upload
```

## Debugging Configuration Errors

When pipeline fails with validation errors:

1. **Check error message** against references/troubleshooting.md
2. **Verify step structure** in references/step-types.md
3. **Validate dependencies** in references/dependencies.md
4. **Don't speculate** - look up the actual validation rules

## Red Flags - You're About to Violate

- "Based on my knowledge of Buildkite..."
- "This syntax should work..."
- "The validator likely fails because..."
- "Let me create a dynamic pipeline..." (without reading docs)
- Writing YAML before reading references
- Confident statements about Buildkite behavior without verification

**All of these mean: STOP. Read the docs first.**

## Real-World Impact

**Without this skill:**
- Agent wrote 2,600-line dynamic pipeline from memory (Scenario 2 baseline)
- Agent speculated about validator behavior without verification (Scenario 3 baseline)
- Agent assumed syntax patterns without checking current docs

**With this skill:**
- Reference official patterns and current syntax
- Validate before proposing
- Avoid outdated or deprecated approaches
Files in this package (48)
  • .gitignore 1 KB
  • README.md 3 KB
  • SKILL.md 9 KB
  • update-docs.sh 1 KB
  • references/artifacts.md 10 KB
  • references/build-meta-data.md 7 KB
  • references/build-retention.md 2 KB
  • references/build-timeouts.md 4 KB
  • references/conditionals.md 16 KB
  • references/defining-steps.md 21 KB
  • references/dependencies.md 9 KB
  • references/dynamic-pipelines.md 6 KB
  • references/environment-variables.md 42 KB
  • references/example-pipelines.md 8 KB
  • references/glob-pattern-syntax.md 7 KB
  • references/index.md 3 KB
  • references/job-minutes.md 2 KB
  • references/links-and-images-in-log-output.md 4 KB
  • references/managing-log-output.md 12 KB
  • references/notifications.md 25 KB
  • references/public-pipelines.md 2 KB
  • references/skipping.md 6 KB
  • references/step-types.md 2 KB
  • references/tags.md 1 KB
  • references/writing-build-scripts.md 7 KB
  • references/buildkite-builder/.gitkeep 1 KB
  • references/buildkite-builder/artifacts.md 3 KB
  • references/buildkite-builder/conditionals.md 5 KB
  • references/buildkite-builder/dependencies.md 4 KB
  • references/buildkite-builder/dsl-syntax.md 3 KB
  • references/buildkite-builder/environment.md 4 KB
  • references/buildkite-builder/extensions.md 5 KB
  • references/buildkite-builder/index.md 3 KB
  • references/buildkite-builder/plugins.md 4 KB
  • references/buildkite-builder/step-attributes.md 3 KB
  • references/buildkite-builder/templates.md 3 KB
  • references/plugins/artifacts.md 2 KB
  • references/plugins/cache.md 4 KB
  • references/plugins/docker-compose.md 5 KB
  • references/plugins/docker.md 3 KB
  • references/plugins/ecr.md 2 KB
  • references/plugins/index.md 2 KB
  • references/workflows/archiving-and-deleting-pipelines.md 2 KB
  • references/workflows/branch-configuration.md 4 KB
  • references/workflows/build-matrix.md 5 KB
  • references/workflows/controlling-concurrency.md 8 KB
  • references/workflows/managing-priorities.md 3 KB
  • references/workflows/scheduled-builds.md 6 KB

Versions

The database has no other skills named developing-pipelines.

Database snapshot: 13.11.2026 · package version a3ef3d70de74 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100buildkite-pipelines
    This skill should be used when the user asks to "write a pipeline", "add caching", "make this build faster", "show test failures in the build page", "add annotations", "only run tests when code changes", "set up dynamic pipelines", "add retry", "parallel steps", "matrix build",…
  • 100buildkite-webhooks
    Receive and verify Buildkite webhooks. Use when setting up Buildkite pipeline webhook handlers, debugging X-Buildkite-Token or X-Buildkite-Signature verification, or handling CI/CD events like build.finished, job.finished, build.failing, or agent.connected.
  • 100buildkite-preflight
    Runs Buildkite CI builds against changes in the local working tree. Use when asked to run preflight or run CI.
  • 90ci-cd-pipeline-builder
    Design and generate CI/CD pipelines from project stack signals across GitHub Actions, GitLab CI, CircleCI, and Buildkite. Use when bootstrapping CI, migrating pipelines, adding deployment gates, or optimizing build times.
  • 82investigating-builds
    Use when the user is working with an existing Buildkite CI run and wants to understand, diagnose, or act on it. Strong signals: a buildkite.com URL, the word "buildkite", the `bk` CLI, the `bktide` tool, or a reference to a specific pipeline, build, or job. Covers intents like:…
  • 100fixing-ci
    Use when CI is failing on a branch, PR, or specific Buildkite build and the user wants to iteratively fix it through verify-locally → push → check → iterate. Strong signals: "fix CI", "make CI green", "CI is failing", "tests are failing in Buildkite", "iterate on this build", a…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.