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