bb-pipelines-author-skill

BB Pipelines Author Skill

An AI skill that teaches coding assistants how to write, review, and improve bitbucket-pipelines.yml configurations. Opinionated, pattern-driven, and test-verified against 60+ official Atlassian documentation pages.

Why

Bitbucket Pipelines YAML has dozens of subtle footguns: mutable image tags, leaked secrets via --build-arg, missing OIDC, Docker cache conflicts, deployment steps without gates, and more. The official documentation is scattered across 60+ Atlassian pages with no single place that ties it all together. This skill encodes all of it -- decision trees, anti-patterns, and production-ready YAML -- into a single reviewable knowledge base that any AI coding assistant can use.

What It Does

The skill operates in two modes:

• Greenfield -- generates production-ready pipelines from project requirements using decision trees and concrete YAML patterns.
• Review -- analyzes existing pipelines and produces a structured report: findings table (CRIT/WARN/INFO), improved YAML, and a changelog.

Coverage includes pipeline architecture, step optimization, caching, Docker builds (BuildKit, multi-arch, Runtime v3), OIDC authentication, deployment orchestration, triggers with expression conditions, monorepo changesets, self-hosted runners, and build minutes optimization.

Installation

Claude Code plugin

claude plugin add bb-pipelines-author-skill

openskills (any compatible agent)

npx openskills install evgenypoyarkov/bb-pipelines-author-skill
npx openskills sync

Manual (contributors)

git clone https://github.com/jenyapoyarkov/bb-pipelines-author-skill.git
cd bb-pipelines-author-skill
just setup claude   # or: just setup opencode

Usage

Open the project in your AI coding tool, then:

# Write a new pipeline
"Create a bitbucket-pipelines.yml for a Node.js monorepo with Docker builds and staging/production deployments"

# Review an existing pipeline
"Review this pipeline:" [paste YAML]

Test Harness

The skill is validated against 8 pipeline fixtures with planted issues:

Fixture	Focus
01-security-gaps	Hardcoded credentials, missing OIDC, :latest tags
02-performance-waste	Missing caches, oversized steps, redundant clones
03-docker-antipatterns	BuildKit misuse, cache conflicts, runtime issues
04-reliability-gaps	Missing retries, no max-time, no after-script
05-clean-pipeline	False positive control (well-architected pipeline)
06-triggers-child-pipelines	Expression triggers, child pipeline constraints
07-monorepo-changesets	Changeset conditions, multi-service monorepo
08-runners-stages	Self-hosted runners, stages, deployment environments

Pass criteria per fixture: >=85% planted hit rate, <=2 true false positives.

Architecture

The project uses a self-improving loop: skill-updater fetches upstream docs and detects drift, skill-builder regenerates the skill from updated reference material, and skill-tester validates the result against fixtures. These three meta-skills are universal engines -- skill-specific configuration lives in _skill-configs/, selected via the .skill-target marker file.

Contributing

Prerequisites

• uv -- Python package manager (also used at review time for inline YAML parsing)
• just -- task runner
• An AI coding tool with the skill loaded (Claude Code, OpenCode, etc.)

Development setup

git clone https://github.com/jenyapoyarkov/bb-pipelines-author-skill.git
cd bb-pipelines-author-skill
just setup claude   # or: just setup opencode

The project uses a .skill-target file to select the active skill configuration from _skill-configs/. Meta-skills (skill-builder, skill-tester, skill-updater) read this to find their target.

Adding a new pattern

Prompt your AI coding tool:

"Create a test fixture in workspace/tests/fixtures/ for [anti-pattern]. Add expected findings in workspace/tests/expected/. Run skill-tester to confirm the gap, then skill-builder to update the skill, then skill-tester again to verify all fixtures pass."

Updating from upstream docs

Prompt your AI coding tool:

"Run the canonical update flow: skill-updater -> skill-builder -> skill-tester. The updater uses two-layer drift detection (hash similarity pre-filter + AI semantic classification) and supports a force option for full sweeps. Fetch upstream docs, regenerate the skill, and verify no regressions."