Claude Skill

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

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download technicalpickles-pickled-claude-plugins-plugins_buildkite_skills_developing-pipelines-8d13327.zip · 94 KB

Install

skills CLI npx skills add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/buildkite/skills/developing-pipelines
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install technicalpickles-pickled-claude-plugins@llmmart
Git 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-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

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:

  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/.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

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 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/ 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 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 for complete list.

Plugin references (see 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 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:

  1. Scan for ENV variable usage
  2. Generate Docker validation command with placeholders
  3. 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:

  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
# 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
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.

No comments yet.

Reviews (0)

No reviews yet.