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
Install
npx skills add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/buildkite/skills/developing-pipelines
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install technicalpickles-pickled-claude-plugins@llmmart
git clone https://github.com/technicalpickles/pickled-claude-plugins.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole technicalpickles/pickled-claude-plugins collection as a plugin from our marketplace. Git is the plain clone.
README
Developing Buildkite Pipelines Skill
This skill ensures Claude references official Buildkite documentation when creating, modifying, or debugging pipeline configurations.
Purpose
Prevents agents from:
- Writing pipeline YAML from memory/training data
- Using outdated or deprecated syntax
- Speculating about configuration errors
- Creating complex implementations without consulting best practices
Structure
developing-buildkite-pipelines/
├── SKILL.md # Main skill document
├── README.md # This file
├── update-docs.sh # Script to refresh documentation
└── references/ # Official Buildkite docs (markdown)
├── index.md # Navigation guide
├── step-types.md # Step configuration reference
├── dynamic-pipelines.md # Dynamic pipeline patterns
├── dependencies.md # Step dependencies
├── environment-variables.md
├── conditionals.md
├── artifacts.md
└── ... (20+ additional reference files)
Updating Documentation
The references/ directory contains markdown versions of official Buildkite documentation. To refresh:
cd plugins/ci-cd-tools/skills/developing-buildkite-pipelines
./update-docs.sh
This fetches the latest docs from buildkite.com/docs/pipelines/configure/** using @mdream/crawl.
When to update:
- Buildkite releases new features
- Syntax changes or deprecations
- Every 3-6 months for general maintenance
Testing Results
Baseline (WITHOUT skill):
- Agent wrote 2,600+ line dynamic pipeline from memory
- No validation strategy mentioned
- Speculated about error causes
- Used patterns from training data
With skill:
- ✅ Referenced official documentation explicitly
- ✅ Mentioned
--dry-runvalidation - ✅ Used current Buildkite patterns
- ✅ Cited specific doc files
See .scratch/buildkite-*-results.md for detailed testing documentation.
Key Behaviors Enforced
- Read docs FIRST - Before proposing YAML, check references
- Validate - Always mention
buildkite-agent pipeline upload --dry-run - Check plugins - Before custom scripts, check buildkite.com/plugins
- Don't speculate - Look up actual validation rules
Dependencies
For updating docs:
- Node.js (for
npx) @mdream/crawlpackage (installed automatically by npx)
References
Skill manifest
Developing Buildkite Pipelines
Overview
Read the matching file under references/ before writing or changing pipeline YAML or pipeline.rb. Training data lags Buildkite's current syntax, plugin options, and deprecations.
Working with Plugins
Before Modifying Plugin Configuration
When editing pipeline steps that use plugins:
- Identify plugins - Note all
plugins:entries in the step - Determine source:
- Default org
buildkite-pluginsif no org specified - Parse explicit org from
{org}/{plugin}#versionformat
- Default org
- Load documentation:
- Cached: Check references/plugins/.md
- Official (not cached): Fetch from Buildkite directory or GitHub
- Internal: Fetch README from
github.com/{org}/{plugin}-buildkite-plugin
- 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?"
- Check references/plugins/index.md for common plugins by category
- Fetch Buildkite directory:
https://buildkite.com/resources/plugins/ - 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)
buildkite-builder generates the pipeline from Ruby. It is in use when both hold:
.buildkite/pipeline.ymlreferences a Docker image containing "buildkite-builder".buildkite/pipeline.rbor.buildkite/pipelines/*/pipeline.rbexists
When it is, edit the pipeline.rb files and read references/buildkite-builder/ alongside the YAML references.
2. Read the reference first
Before writing the change, read the matching file in references/ for YAML, or in references/buildkite-builder/ for pipeline.rb.
Available references:
step-types.md- Command, trigger, block, wait, input stepsdynamic-pipelines.md- Generating steps programmaticallydependencies.md- Using depends_on, parallel stepsenvironment-variables.md- Setting and using env varsconditionals.md- if/branches for conditional executionartifacts.md- Uploading and downloading build artifacts
See references/index.md for complete list.
Plugin references (see references/plugins/index.md for full list):
plugins/docker.md- Docker container executionplugins/docker-compose.md- Multi-container environmentsplugins/artifacts.md- Artifact upload/downloadplugins/ecr.md- AWS ECR authenticationplugins/cache.md- Dependency caching
buildkite-builder references (when detected):
buildkite-builder/index.md- Overview and when to usebuildkite-builder/dsl-syntax.md- Core DSL step typesbuildkite-builder/step-attributes.md- Common attributesbuildkite-builder/templates.md- Reusable step templatesbuildkite-builder/extensions.md- Custom DSL and extensionsbuildkite-builder/conditionals.md- Conditional step generationbuildkite-builder/dependencies.md- Step dependenciesbuildkite-builder/artifacts.md- Artifact handlingbuildkite-builder/plugins.md- Plugin usage in DSLbuildkite-builder/environment.md- Environment variables
See references/buildkite-builder/index.md for complete guide.
3. Validate Syntax
Validate before proposing the change. When no validator is installed, give the user the command instead.
# Schema check with the bk CLI, local, no API token
bk pipeline validate --file .buildkite/pipeline.yml
# Or with buildkite-agent, where it is installed
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:
- Scan for ENV variable usage
- Generate Docker validation command with placeholders
- List detected environment variables
# 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:<tag from .buildkite/pipeline.yml>
# 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
For any step with a plugins: block, follow Working with Plugins before changing it.
buildkite-builder Troubleshooting Mode
When user mentions errors, "not generating", "YAML looks wrong", or validation failures with buildkite-builder:
- Read pipeline.rb - Understand the Ruby DSL
- Run Docker command - Generate YAML to see actual output
- Compare output - Expected vs actual YAML
- Reference both docs - buildkite-builder DSL AND Buildkite YAML docs
- Identify issue - Where Ruby DSL produces unexpected YAML
- Propose fix - Modify pipeline.rb to fix generation
This mode switches from Ruby-first to YAML-aware debugging.
Dynamic Pipelines Pattern
When generating steps programmatically:
- Reference dynamic-pipelines.md for current patterns
- Use Buildkite SDK if available (see dynamic-pipelines.md)
- Validate generated output with --dry-run
- Consider official examples before custom implementations
# Standard pattern from official docs
.buildkite/pipeline.sh | buildkite-agent pipeline upload
Debugging Configuration Errors
When pipeline fails with validation errors:
- Verify step structure in references/step-types.md
- Validate dependencies in references/dependencies.md
- Don't speculate - look up the actual validation rules
Files (pickled-claude-plugins)
-
references
-
buildkite-builder
-
.gitkeep 72 B · in bundle
-
artifacts.md 2.7 KB
Loading… -
conditionals.md 4.8 KB
Loading… -
dependencies.md 3.9 KB
Loading… -
dsl-syntax.md 3.1 KB
Loading… -
environment.md 4.1 KB
Loading… -
extensions.md 4.7 KB
Loading… -
index.md 2.7 KB
Loading… -
plugins.md 3.8 KB
Loading… -
step-attributes.md 3.4 KB
Loading… -
templates.md 3 KB
Loading…
-
-
plugins
-
artifacts.md 2.5 KB
Loading… -
cache.md 3.5 KB
Loading… -
docker-compose.md 4.5 KB
Loading… -
docker.md 3.4 KB
Loading… -
ecr.md 2.5 KB
Loading… -
index.md 1.9 KB
Loading…
-
-
workflows
-
archiving-and-deleting-pipelines.md 2.3 KB
Loading… -
branch-configuration.md 4.1 KB
Loading… -
build-matrix.md 4.8 KB
Loading… -
controlling-concurrency.md 8.1 KB
Loading… -
managing-priorities.md 3 KB
Loading… -
scheduled-builds.md 5.6 KB
Loading…
-
-
artifacts.md 9.9 KB
Loading… -
build-meta-data.md 6.5 KB
Loading… -
build-retention.md 1.7 KB
Loading… -
build-timeouts.md 3.8 KB
Loading… -
conditionals.md 16 KB
Loading… -
defining-steps.md 21 KB
Loading… -
dependencies.md 8.7 KB
Loading… -
dynamic-pipelines.md 5.6 KB
Loading… -
environment-variables.md 42.3 KB
Loading… -
example-pipelines.md 8.5 KB
Loading… -
glob-pattern-syntax.md 6.6 KB
Loading… -
index.md 2.7 KB
Loading… -
job-minutes.md 2.1 KB
Loading… -
links-and-images-in-log-output.md 4.3 KB
Loading… -
managing-log-output.md 12.2 KB
Loading… -
notifications.md 24.6 KB
Loading… -
public-pipelines.md 1.6 KB
Loading… -
skipping.md 6 KB
Loading… -
step-types.md 1.8 KB
Loading… -
tags.md 1.5 KB
Loading… -
writing-build-scripts.md 6.9 KB
Loading…
-
-
.gitignore 9 B · in bundle
-
README.md 2.5 KB
# Developing Buildkite Pipelines Skill This skill ensures Claude references official Buildkite documentation when creating, modifying, or debugging pipeline configurations. ## Purpose Prevents agents from: - Writing pipeline YAML from memory/training data - Using outdated or deprecated syntax - Speculating about configuration errors - Creating complex implementations without consulting best practices ## Structure ``` developing-buildkite-pipelines/ ├── SKILL.md # Main skill document ├── README.md # This file ├── update-docs.sh # Script to refresh documentation └── references/ # Official Buildkite docs (markdown) ├── index.md # Navigation guide ├── step-types.md # Step configuration reference ├── dynamic-pipelines.md # Dynamic pipeline patterns ├── dependencies.md # Step dependencies ├── environment-variables.md ├── conditionals.md ├── artifacts.md └── ... (20+ additional reference files) ``` ## Updating Documentation The `references/` directory contains markdown versions of official Buildkite documentation. To refresh: ```bash cd plugins/ci-cd-tools/skills/developing-buildkite-pipelines ./update-docs.sh ``` This fetches the latest docs from `buildkite.com/docs/pipelines/configure/**` using `@mdream/crawl`. **When to update:** - Buildkite releases new features - Syntax changes or deprecations - Every 3-6 months for general maintenance ## Testing Results ### Baseline (WITHOUT skill): - Agent wrote 2,600+ line dynamic pipeline from memory - No validation strategy mentioned - Speculated about error causes - Used patterns from training data ### With skill: - ✅ Referenced official documentation explicitly - ✅ Mentioned `--dry-run` validation - ✅ Used current Buildkite patterns - ✅ Cited specific doc files See `.scratch/buildkite-*-results.md` for detailed testing documentation. ## Key Behaviors Enforced 1. **Read docs FIRST** - Before proposing YAML, check references 2. **Validate** - Always mention `buildkite-agent pipeline upload --dry-run` 3. **Check plugins** - Before custom scripts, check buildkite.com/plugins 4. **Don't speculate** - Look up actual validation rules ## Dependencies For updating docs: - Node.js (for `npx`) - `@mdream/crawl` package (installed automatically by npx) ## References - [Buildkite Pipeline Documentation](https://buildkite.com/docs/pipelines/configure) - [Writing Skills Guide](../../superpowers/skills/writing-skills/SKILL.md) -
SKILL.md 6.4 KB
--- 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 Read the matching file under `references/` before writing or changing pipeline YAML or `pipeline.rb`. Training data lags Buildkite's current syntax, plugin options, and deprecations. ## 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) buildkite-builder generates the pipeline from Ruby. It is in use when both hold: - `.buildkite/pipeline.yml` references a Docker image containing "buildkite-builder" - `.buildkite/pipeline.rb` or `.buildkite/pipelines/*/pipeline.rb` exists When it is, edit the `pipeline.rb` files and read [references/buildkite-builder/](references/buildkite-builder/index.md) alongside the YAML references. ### 2. Read the reference first Before writing the change, read the matching file in [references/](references/index.md) for YAML, or in [references/buildkite-builder/](references/buildkite-builder/index.md) for `pipeline.rb`. **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 Validate before proposing the change. When no validator is installed, give the user the command instead. ```bash # Schema check with the bk CLI, local, no API token bk pipeline validate --file .buildkite/pipeline.yml # Or with buildkite-agent, where it is installed 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:<tag from .buildkite/pipeline.yml> # 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 For any step with a `plugins:` block, follow [Working with Plugins](#working-with-plugins) before changing it. ## 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. ## 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. **Verify step structure** in references/step-types.md 2. **Validate dependencies** in references/dependencies.md 3. **Don't speculate** - look up the actual validation rules -
update-docs.sh 1.4 KB
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.